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Preface 


The  X  Toolkit  is  the  collective  name  for  two  subroutine  libraries  designed  to  simplify  the 
development  of  X  Window  System  applications — the  Xt  Intrinsics  and  the  Xaw  widget  set 
A  widget  is  a  pre-built  user-interface  component  The  Xt  library  consists  of  routines  for 
building  and  using  widgets.  Xt  is  written  using  Xlib,  the  lowest  level  C-language  interface  to 
the  X  Window  System.  Both  the  Xt  Intrinsics  and  Xlib  are  required  by  the  X  standard  (esta 
blished  by  the  X  Consortium)  on  any  system  that  allows  programming  of  X  applications  in  C. 

The  Xaw  widget  library  is  based  on  Xt  and  provides  a  small  number  of  widgets  that  can  be 
used  to  write  simple  application  programs.  Xaw  was  developed  by  MIT's  Project  Athena, 
and  the  acronym  Xaw  stands  for  "Athena  Widgets."  Xaw  was  designed  as  a  simple  demon 
stration  and  test  of  the  Intrinsics — not  as  a  complete  set  of  widgets  for  writing  demanding 
applications.  There  are  numerous  other  widget  sets  provided  by  system  vendors  to  imple 
ment  their  particular  user-interface  styles.  The  two  most  widely-used  are  OSF's  Motif,  and 
AT&T's  OPEN  LOOK  widget  set 

This  book  describes  how  to  build  applications  using  the  Xt  Intrinsics.  It  provides  a  complete 
tutorial  with  programming  examples. 

The  book  uses  the  Athena  widgets  to  demonstrate  how  to  use  existing  widgets,  but  it  is 
equally  applicable  to  and  provides  a  good  introduction  to  programming  with  any  other 
widget  set  based  on  Xt.  It  is  based  on  Release  3  of  the  Intrinsics  and  the  Athena  widgets,  but 
with  the  permission  of  the  X  Consortium  staff,  includes  some  advance  information  on 
Release  4,  based  on  the  Beta  release  to  Consortium  members. 


Summary  of  Contents 

The  discussion  of  the  X  Toolkit  is  divided  into  three  volumes,  Volumes  Four,  Five,  and  Six  of 
the  X  Window  System  Series  available  from  O'Reilly  &  Associates,  Inc. 

This  is  the  first  of  the  three,  Volume  Four,  X  Toolkit  Intrinsics  Programming  Manual.  It  pro 
vides  an  explanation  of  the  X  Toolkit,  including  tutorial  material  and  numerous  programming 
examples.  Arranged  by  task  or  topic,  each  chapter  brings  together  a  group  of  Xt  functions, 
describes  the  conceptual  foundation  on  which  they  are  based,  and  illustrates  how  they  are 
most  often  used  in  writing  applications.  This  volume  is  structured  to  be  useful  as  a  tutorial 
and  also  as  a  task-oriented  reference. 
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Volume  Five,  the  X  Toolkit  Intrinsics  Reference  Manual,  includes  reference  pages  for  each  of 
the  Xt  functions,  as  well  as  for  the  widget  classes  defined  by  Xt,  organized  alphabetically  for 
ease  of  reference;  a  permuted  index;  and  numerous  appendices  and  quick  reference  aids. 

Volume  Six,  the  X  Toolkit  Widget  Reference  Manual,  includes  reference  pages  for  each  of  the 
most  widely  used  widget  sets:  the  Athena  widgets,  developed  by  MIT  as  a  demonstration  of 
Xt,  the  OPEN  LOOK  widgets  from  AT&T,  and  the  Open  Software  Foundation's  Motif  widget 
set  This  volume  will  be  available  in  mid  1990. 

The  three  volumes  are  designed  to  be  used  together.  To  get  the  most  out  of  the  examples  in 
Volume  Four,  you  will  need  the  exact  calling  sequences  of  each  function  from  Volume  Five. 
To  understand  fully  how  to  use  each  of  the  functions  described  in  Volume  Five,  all  but  the 
most  experienced  Toolkit  "hacker"  will  need  the  explanation  and  examples  in  Volume  Four. 
Volume  Six  provides  the  details  on  the  actual  widgets  you  can  use  to  build  your  applications. 
Instead  of  Volume  Six,  you  can  use  the  widget  documentation  provided  by  your  system  ven 
dor.  Until  Volume  Six  is  available,  the  Athena  Widget  reference  pages  will  be  duplicated  in 
Volume  Five. 

All  three  volumes  include  material  from  the  original  Toolkit  documentation  provided  by 
MIT,  though  in  Volume  Four  this  is  mostly  limited  to  the  appendices.  We  have  done  our  best 
to  incorporate  all  the  useful  information  from  the  MIT  documentation,  to  correct  references 
we  found  to  be  in  error,  to  reorganize  and  present  it  in  a  more  useful  form,  and  to  supplement 
it  with  conceptual  material,  tutorials,  reference  aids,  and  examples.  In  other  words,  this  man 
ual  is  not  only  a  replacement,  but  is  a  superset  of  the  MIT  documentation. 

Those  of  you  familiar  with  the  MIT  documentation  will  recognize  that  each  reference  page  in 
Volume  Five  includes  the  detailed  description  of  the  routine  found  in  X  Toolkit  Intrinsics — C 
Language  Interface,  plus  in  many  cases  additional  text  that  clarifies  ambiguities  and 
describes  the  context  in  which  the  routine  would  be  used.  We  have  also  added  cross- 
references  to  related  reference  pages  and  to  where  additional  information  can  be  found  in 
Volume  Four. 


Assumptions 

This  book  makes  no  assumptions  about  the  reader's  knowledge  of  object-oriented  program 
ming  or  the  X  Window  System.  Readers  should  be  proficient  in  the  C  programming  lan 
guage,  although  examples  are  provided  for  infrequently  used  features  of  the  language  that  are 
necessary  or  useful  when  programming  with  the  X  Toolkit.  In  addition,  general  familiarity 
with  the  principles  of  raster  graphics  will  be  helpful. 

However,  the  X  Toolkit  is  not  self-sufficient.  Even  though  the  Toolkit  is  intended  to  hide  the 
low-level  X  interface  provided  by  Xlib,  there  are  times  in  writing  applications  or  widgets 
when  Xlib  functions  will  be  necessary  because  no  Xt  feature  exists  to  do  the  same  thing. 
This  book  describes  the  most  common  occasions  for  using  Xlib,  but  does  not  provide  a  refer 
ence  to  the  particular  functions  involved.  Additional  documentation  on  Xlib,  such  as  that 
provided  by  Volume  One,  Xlib  Programming  Manual,  and  Volume  Two,  Xlib  Reference 
Manual,  will  be  indispensable. 
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Related  Documents 

Five  other  books  on  the  X  Window  System  are  available  from  O'Reilly  &  Associates,  Inc.: 
Volume  Zero       X  Protocol  Reference  Manual 
Volume  One        Xlib  Programming  Manual 
Volume  Two       Xlib  Reference  Manual 
Volume  Three     X  Window  System  User' s  Guide 
Volume  Seven     XView  Programming  Manual 

The  following  documents  are  included  on  the  XI 1  source  tape: 

X  Toolkit  Intrinsics — C Language  Interface,  by  Joel  McCormack,  Paul  Asente, 

and  Ralph  Swick 
X  Toolkit  Athena  Widgets — C  Language  Interface,  by  Ralph  Swick  and 

Terry  Weissman 
Xlib — C  Language  X  Interface,  by  Jim  Gettys,  Ron  Newman,  and  Robert  Scheifler 

The  following  Nutshell  Handbooks  published  by  O'Reilly  and  Associates,  Inc.,  are  useful 
when  programming  in  C: 

Checking  C  Programs  with  lint,  by  Ian  Darwin 
Managing  Projects  with  make,  by  Steve  Talbott 
Using  C  on  the  UNIX  System,  by  Dave  Curry 

The  following  is  the  classic  introduction  to  C  programming: 

The  C  Programming  Language,  by  B.  W.  Kernighan  and  D.  M.  Ritchie 

How  to  Use  This  Manual 


Volume  Four  treats  both  application  programming  with  widgets  and  widget  programming 
(the  design  and  coding  of  new  widgets). 

The  first  four  chapters  treat  widgets  largely  as  "black  boxes,"  which  is  appropriate,  consider 
ing  the  object-oriented  philosophy  of  the  Toolkit  These  chapters  also  provide  an  overview 
of  many  elements  of  the  X  Toolkit,  and  so  are  appropriate  for  all  readers. 

Chapter  1,  Introduction  to  the  X  Window  System,  provides  a  discussion  of  the  context  in 
which  X  programs  operate.  Programmers  who  are  comfortable  programming 
with  Xlib  can  skip  Chapter  1. 

Chapter  2,  Introduction  to  the  X  Toolkit,  describes  the  conceptual  foundations  underlying 
Toolkit  programming,  and  shows  how  to  write  simple  programs  that  use 
widgets  from  existing  widget  sets.  It  introduces  such  fundamental  Toolkit 
programming  concepts  as  resources,  the  Translation  Manager,  callbacks,  and 
actions. 
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Chapter  3,  More  Widget  Programming  Techniques,  describes  how  to  use  some  of  the 
more  complex  widgets  found  in  applications,  including  composite  widgets, 
constraint  widgets,  and  pop  ups.  It  also  describes  how  to  define  application 
resources  and  command-line  options,  and  how  to  hardcode  the  value  of  widget 
resources  when  you  create  a  widget  Finally,  it  describes  how  to  create  multi 
ple  top-level  windows,  and  how  to  use  application  contexts  to  create  applica 
tions  that  run  on  more  than  one  processor. 

Chapter  4,  An  Example  Application,  describes  a  complete  application,  in  several  itera 
tions.  First,  it  shows  a  simple  version  of  the  program,  a  bitmap  editor,  as  it 
would  be  written  assuming  the  existence  of  a  BitmapEdit  widget  (which  is 
actually  developed  in  Chapter  5).  Then,  two  refined  versions  are  developed, 
each  demonstrating  additional  Toolkit  programming  techniques.  Finally,  the 
same  application  is  shown  as  it  would  be  written  if  the  bitmap  editor  were 
implemented  in  an  application  window  rather  than  with  the  BitmapEdit 
widget 

The  next  two  chapters  describe  widget  internals,  and  the  process  of  creating  new  widgets. 
While  this  information  is  not  essential  for  application  programmers,  it  will  help  even  some 
one  uninterested  in  writing  new  widgets  to  understand  the  sometimes  peculiar  style  of 
Toolkit  programming. 

Chapter  5,  Inside  a  Widget,  describes  the  code  inside  a  widget  Much  of  this  code  is 
common  to  all  widgets.  You  can  think  of  it  as  a  framework  that  Xt  uses  to 
implement  a  widget's  features.  After  reading  this  chapter,  you  should  under 
stand  the  procedure  for  creating  your  own  widget  around  this  framework. 

Chapter  6,  Basic  Widget  Methods,  describes  a  widget's  initialize,  expose, 
set_values,  destroy,  resize  and  query_geometry  methods.  (A 
widget's  methods  are  internal  routines  called  automatically  by  Xt  to  give  the 
widget  a  degree  of  independence  from  the  application.)  The  chapter  explains 
when  Xt  calls  each  method,  and  describes  in  detail  what  should  be  in  each  of 
these  methods.  Among  other  things,  these  methods  prepare  for  and  do  the 
drawing  of  graphics  that  appear  in  a  widget  This  chapter  describes  what  the 
Toolkit  adds  to  the  graphics  model  provided  by  Xlib,  but  does  not  describe  in 
detail  how  to  draw  using  Xlib;  this  topic  is  described  in  Chapters  5, 6,  and  7  of 
Volume  One,  Xlib  Programming  Manual. 

Later  chapters  treat  various  topics  of  interest  to  either  application  or  widget  programmers,  or 
both.  Some  of  these  topics  have  been  introduced  in  the  earlier  chapters,  and  are  explored 
more  completely  in  the  later  ones. 

Chapter  7,  Events,  Translations,  and  Accelerators,  describes  the  complete  syntax  of 
translation  tables,  which  allow  the  user  to  configure  the  mapping  of  event 
sequences  into  widget  actions.  It  also  describes  accelerators,  a  mechanism  for 
mapping  events  in  one  widget  to  actions  in  another. 

Chapter  8,  More  Input  Techniques,  describes  how  to  handle  events  with  event  handlers, 
and  how  to  use  information  from  the  event  structure  inside  an  event  handler  or 
action  routine.  It  also  describes  how  to  get  file,  pipe,  or  socket  input,  how  to 
use  timeouts  to  call  a  function  after  a  delay  or  at  particular  intervals,  and  how 
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to  use  work  procedures  to  do  background  processing.  Finally,  it  discusses 
some  low-level  features  of  Xt  for  directly  interacting  with  the  event  queue. 

Chapter  9,  Resource  Management  and  Type  Conversion,  is  a  more  thorough  discussion  of 
how  resources  work  and  how  they  should  be  used.  This  chapter  describes  in 
detail  the  resource  file  format  and  the  rules  that  govern  the  precedence  of 
resource  settings.  It  also  describes  how  to  add  your  own  type  converter  so  that 
you  can  set  application-  or  widget-specific  data  through  resources.  Finally,  it 
describes  subresources  and  how  to  use  them. 

Chapter  10,  Inter  client  Communications,  discusses  communication  through  the  X  server 
between  application  and  the  window  manager,  and  between  two  applications. 
The  application-window  manager  communication  is  performed  by  code  in  the 
Shell  widget.  The  application  sets  shell  resources  to  control  this  communica 
tion  with  the  window  manager.  Application-application  communication  is 
usually  done  with  a  process  called  selections.  This  form  of  communication  is 
already  implemented  in  most  widgets  that  display  text,  but  you  may  want  to 
implement  it  in  your  own  custom  widgets.  Selections  can  also  pass  other 
kinds  of  data  such  as  graphics. 

Chapter  11,  Geometry  Management,  discusses  how  composite  and  constraint  widgets  man 
age  the  layout  of  widgets,  and  how  to  write  your  own  simple  composite  and 
constraint  widgets. 

Chapter  12,  Menus,  Gadgets,  and  Cascaded  Pop  Ups,  describes  how  menus  work,  and  sev 
eral  ways  to  create  menu  widgets.  One  of  these  ways  involves  the  use  of  win- 
dowless  widgets,  or  gadgets.  This  chapter  also  describes  how  to  use  more 
advanced  features  of  the  Xt  pop-up  mechanism,  including  modal  cascades,  to 
implement  cascading  pop-up  menus. 

Chapter  13,  Miscellaneous  Toolkit  Programming  Techniques,  describes  various  Xt  func 
tions  that  have  not  been  treated  elsewhere  in  the  book.  These  include  func 
tions  for  error  and  warning  handling,  case  conversion,  and  so  on. 

Appendix  A,  OPEN  WOK  and  Motif,  provides  an  overview  of  the  widgets  available  in 
AT&T's  OPEN  LOOK  widget  set  and  OSF's  Motif.  These  widgets  are  con 
trasted  with  those  in  the  Athena  widget  set. 

Appendix  B,  The  Varargs  Interfaces,  describes  Dan  Heller's  WidgetWrap  library  available 
for  Release  3,  and  Xt's  own  varargs  interface  introduced  in  Release  4.  These 
libraries  clean  up  Xt's  application  programming  interface. 

Appendix  C,  Specifying  Fonts  and  Colors,  gives  information  on  the  values  that  can  be  used 
when  specifying  fonts  and  colors  as  resources. 

Appendix  D,  Naming  Conventions,  describes  a  suggested  set  of  conventions  for  naming 
widgets  and  elements  with  widget  code. 

Appendix  E,  Converting  Widgets  from  XI 1  Release  2  to  XI 1  Release  3,  describes  the 
changes  between  Release  2  (which  was  the  first  release  of  the  Toolkit)  and 
Release  3.  This  manual  describes  Release  3,  but  notes  any  changes  necessary 
to  make  the  code  work  in  other  releases. 
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Appendix  F,  The  xbitmap  Application,  shows  the  complete  code  for  all  versions  of  the  xbit- 
map  application  and  the  BitmapEdit  widget,  which  are  described  in  Chapters 
4  and  5. 

Appendix  G,  Sources  of  Additional  Information,  lists  where  to  get  the  X  software,  compa 
nies  that  offer  training  in  X  programming,  and  description  of  additional  books 
on  the  subject  that  have  been  or  will  be  published  soon. 

Glossary  This  section  gives  you  somewhere  to  turn  should  you  run  across  an  unfamiliar 
term.  Some  care  has  been  taken  to  see  that  all  terms  are  defined  where  they 
are  first  used  in  the  text,  but  not  everyone  will  read  the  manual  in  sequential 
order. 

Master  Index  provides  a  thorough,  combined  index  to  Volumes  Four  and  Five,  making  it 
easy  to  look  up  all  the  appropriate  references  to  a  topic,  in  either  volume. 

Volume  Five  consists  of  a  permuted  index,  reference  pages  to  each  library  function,  and 
appendices  that  cover  macros,  structures,  and  defined  symbols. 

Font  Conventions  Used  in  This  Manual 


Italics  are  used  for: 

•  UNIX  pathnames,  filenames,  program  names,  user  command  names,  and  options  for  user 
commands 

•  New  terms  where  they  are  defined 

Typewriter   Font  is  used  for: 

•  Anything  that  would  be  typed  verbatim  into  code,  such  as  examples  of  source  code  and 
text  on  the  screen 

•  The  contents  of  include  files,  such  as  structure  types,  structure  members,  symbols 
(defined  constants  and  bit  flags),  and  macros 

•  Xt,  Xaw,  and  Xlib  functions 

•  Names  of  subroutines  in  the  example  programs 

Italic   Typewriter  Fon t  is  used  for: 

•  Arguments  to  functions,  since  they  could  be  typed  in  code  as  shown  but  are  arbitrary 

Helvetica  Italics  are  used  for: 

•  Titles  of  examples,  figures,  and  tables 

Boldface  is  used  for: 

•  Chapter  and  section  headings 
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Requests  for  Comments 

To  help  us  provjde  you  with  the  best  documentation  possible,  please  write  to  tell  us  about  any 
flaws  you  find  in  this  manual  or  how  you  think  it  could  be  improved. 

Our  U.S.  mail  address,  e-mail  address,  and  phone  numbers  are  as  follows: 

O'Reilly  &  Associates,  Inc. 
632  Petaluma  Avenue 
Sebastopol,  CA  95472 
800-338-6887,  in  CA  800-533-6887 
international  +1  707-829-0515 

UUCP:  uunet!ora!adrian  Internet:  adrian@ora.com 

Bulk  Sales  Information 


This  manual  is  being  resold  as  the  official  X  Window  System  documentation  by  many  work 
station  manufacturers.  For  information  on  volume  discounts  for  bulk  purchase,  call  O'Reilly 
and  Associates,  Inc.,  at  800-338-6887  (in  California,  800-533-6887),  or  send  e-mail  to 
linda@ora.com. 

For  companies  requiring  extensive  customization  of  the  book,  source  licensing  terms  are  also 
available. 


Obtaining  the  X  Window  System  Software 

The  X  Window  system  is  copyrighted  but  freely  distributed.  The  only  restriction  this  places 
on  its  use  is  that  the  copyright  notice  identifying  the  author  and  the  terms  of  use  must  accom 
pany  all  copies  of  the  software  or  documentation.  Thanks  to  this  policy,  the  software  is  avail 
able  for  nominal  cost  from  a  variety  of  sources.  See  Appendix  G,  Sources  of  Additional 
Information,  for  a  listing  of  these  sources. 
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Example  Programs 

The  example  programs  in  this  book  are  on  the  XI 1  Release  4  distribution  in  the  contributed 
section.  There  are  many  ways  of  getting  this  distribution;  most  are  described  in  Appendix  G. 

The  example  programs  are  also  available  free  from  UUNET  (that  is,  free  except  for  UUNET's 
usual  connect-time  charges).  If  you  have  access  to  UUNET,  you  can  retrieve  the  source  code 
using  uucp  or  ftp.  For  uucp,  find  a  machine  with  direct  access  to  UUNET,  and  type  the  fol 
lowing  command: 

uucp   uunet\ ! ~uucp/nutshell/Xt/xtprogs . tar . Z    yowrhosN.~ /yourname/ 

The  backslashes  can  be  omitted  if  you  use  the  bourne  shell  (sh)  instead  of  csh.  The  file 
should  appear  some  time  later  (up  to  a  day  or  more)  in  the  directory  lusrlspoolluucppub- 
liclyourname. 

To  usQftp,ftp  to  uunet.uu.net  and  use  anonymous  as  your  user  name  and  guest  as  your  pass 
word.  Then  type  the  following: 

cd  /nutshell/Xt 

binary    (you  must  specify  binary  transfer  for  compressed  files) 

get  xtprogs . shar . Z 

bye 

The  file  is  a  compressed  shell  archive.  To  restore  the  files  once  you  have  retrieved  the 
archive,  type: 

uncompress  xtprogs. shar 
sh  xtprogs. shar 

The  example  programs  will  also  be  available  free  by  ftp  from  expo.lcs.mit.edu  soon  after 
Release  4  is  released.  However,  the  exact  location  and  filename  of  the  file  or  files  containing 
the  examples  was  not  available  at  press  time.  The  filename  and  directory  will  not  be  the 
same  as  those  described  for  UUNET. 

The  examples  will  be  installed  in  subdirectories  under  the  current  directory,  one  for  each 
chapter  in  the  book.  Imakefiles  are  included.  (Imakefiles  are  used  with  imake,  a  program 
supplied  with  the  XI 1  distribution  that  generates  proper  Makefiles  on  a  wide  variety  of  sys 
tems.) 

All  the  application-defaults  files  are  in  the  main  examples  directory.  The  application- 
defaults  files  are  not  automatically  installed  in  the  system  application-defaults  directory 
(lusrlliblXlllapp-defaults  on  UNIX  systems).  (See  Chapter  9,  Resource  Management  and 
Type  Conversion,  for  details.)  If  you  have  permission  to  write  to  that  directory,  you  can  copy 
them  there  yourself.  Otherwise,  you  can  set  the  XAPPLRESDIR  environment  variable  to  the 
complete  path  of  the  directory  where  you  installed  the  examples.  The  value  of  XAPPLRES 
DIR  must  end  with  a  /  (slash).  (Many  of  the  examples  will  not  function  properly  without  the 
application-defaults  files.) 
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Introduction  to  the  X  Window  System 


This  chapter  introduces  many  of  the  most  important  concepts  on  which  the  X 
Window  System  is  based,  and  describes  the  environment  in  which  the  X 
Toolkit  operates.  This  chapter  assumes  that  you  are  new  to  programming  the 
X  Window  System.  If  you  already  have  some  experience  programming  the  X 
Window  System,  you  may  wish  to  skim  this  Chapter  for  a  brief  review  or  even 
begin  with  Chapter  2. 


In  This  Chapter: 

The  Server  and  Client 6 

The  Software  Hierarchy 8 

Event-driven  Programming  10 

The  Window  Manager 11 

Extensions  to  X  .  ..12 
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Introduction  to  the  X  Window  System 


The  X  Window  System  (or  simply  X)*  is  a  hardware-independent  windowing  system  for 
workstations.  It  was  developed  jointly  by  MIT  and  Digital  Equipment  Corporation,  and  has 
been  adopted  by  the  computer  industry  as  a  standard  platform  for  graphics  applications. 

X  controls  a  "bit-mapped"  display  in  which  every  pixel  (dot  on  the  screen)  is  individually 
controllable.  This  allows  applications  to  draw  pictures  as  well  as  text.  Until  recently,  indi 
vidual  control  of  screen  pixels  was  widely  available  only  on  personal  computers  (PCs)  and 
high-priced  technical  workstations.  Most  general-purpose  machines  were  limited  to  output 
on  text-only  terminals.  X  brings  a  consistent  world  of  graphic  output  to  both  PCs  and  more 
powerful  machines.  Figure  1-1  compares  an  X  application  to  an  application  running  on  a  tra 
ditional  text  terminal. 

Like  other  windowing  systems,  X  divides  the  screen  into  multiple  input  and  output  areas 
called  windows.  Using  a  terminal  emulator,  windows  can  act  as  "virtual  terminals,"  running 
ordinary  text-based  applications.  However,  as  shown  in  Figure  1-1,  windows  can  also  run 
applications  designed  to  take  advantage  of  the  graphic  power  of  the  bitmapped  display. 

X  takes  user  input  from  a  pointer.  The  pointer  is  usually  a  mouse  but  could  just  as  well  be  a 
track-ball  or  a  tablet.  The  pointer  allows  the  user  to  control  a  program  without  using  the  key 
board,  by  pointing  at  objects  drawn  on  the  screen  such  as  menus  and  command  buttons.  This 
method  of  using  programs  is  often  easier  to  learn  than  traditional  keyboard  control,  because  it 
is  more  intuitive.  Figure  1-2  shows  an  application  with  a  typical  three-button  pointer  being 
used  to  select  a  menu  item. 

Of  course,  X  also  handles  keyboard  input.  The  pointer  directs  the  keyboard  focus  from  win 
dow  to  window.  Only  one  window  at  a  time  can  receive  keyboard  input. 

In  X,  as  in  many  other  window  systems,  each  application  need  not  (and  usually  does  not) 
consist  of  only  a  single  window.  Any  part  of  an  application  can  have  its  own  separate 
subwindow,  which  simplifies  the  management  of  input  and  output  within  the  application 
code.  Such  child  windows  are  visible  only  within  the  confines  of  their  parent  window. 

Windows  are  rectangular  and  oriented  along  the  same  axes  as  the  edges  of  the  display.  Each 
window  has  its  own  coordinate  system,  with  the  origin  in  the  upper-left  corner  of  the  window 
inside  its  border.  The  application  or  the  user  can  change  the  dimensions  of  windows.  Figure 


"The  name  "X  Windows"  is  frowned  upon  by  the  developers  of  X. 
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X  Window  System 


Text  Terminal 


Figure  1-1.  An  X  application,  and  an  application  on  a  traditional  text  terminal 


Figure  1-2.  A  three-button  mouse  directing  the  pointer  to  select  a  menu  item 

1-3  shows  a  typical  screen  with  several  virtual  terminals  running.  The  screen  also  shows 
some  applications,  such  as  xmh,  xclock,  and  xload,  that  run  in  their  own  windows. 

X  supports  both  color  and  black-and-white  displays. 
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xterm  windows 


xclock  window 


iconified  xterm  window 


\ 


%  rlogin  host2 


Dear  Mr.  Hoffmann: 
.LP 

You  called  yesterday  for 
information  about  X. 
The  X  Window  System  is 
network-based  graphic 
window  system  that  was 
developed  jit  JMJT  in  1 984.  C 

The  X  Window  System  is  a 
network-based  graphic  window 
system  that  was  developed  at  MIT 
in  1984.  Several  versions  of  X 
have  been  developed,  the  most 
recent  of  which  is  X  Version  1 1 
(X11),  first  released  in  1987.  X1 1 


\ 


Figure  1-3.  Screen  layout  of  a  typical  user's  X  Window  System 

Many  of  the  above  characteristics  are  also  true  of  several  other  window  systems.  What  is 
unusual  about  X  is  that  it  is  based  on  a  network  protocol  instead  of  on  system-specific  proce 
dure  and  system  calls.  This  network  protocol  enables  X  to  be  ported  to  different  computer 
architectures  and  operating  systems;  it  also  allows  programs  to  run  on  one  architecture  while 
displaying  on  another.  Because  of  its  unique  design,  X  can  make  a  network  of  different  com 
puters  cooperate.  For  example,  a  computationally  intensive  application  might  run  on  a  super 
computer,  but  take  input  from  and  display  output  on  a  workstation  connected  across  a  local 
area  network.  To  the  user,  the  application  would  simply  appear  to  be  running  on  the  work 
station. 
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1 .1  The  Server  and  Client 

To  allow  programs  to  be  run  on  one  machine  and  display  on  another,  X  was  designed  as  a  net 
work  protocol — a  predefined  set  of  requests  and  replies — between  two  processes,  one  of 
which  is  an  application  program  called  a  client,  and  the  other  of  which,  the  server,  controls 
the  display  hardware,  keyboard,  and  pointer. 

The  user  sits  at  the  machine  running  the  server.  At  first,  this  usage  of  the  term  server  may 
seem  a  little  odd,  since  file  and  print  servers  are  normally  remote  machines.  But  the  usage  is 
consistent.  The  local  display  is  accessible  to  other  systems  across  the  network,  and  for  those 
systems  the  X  server  does  act  like  other  types  of  server. 

The  X  server  acts  as  an  intermediary  between  user  programs  and  the  resources  of  the  local 
system  such  as  the  keyboard  and  screen.  It  contains  all  device-specific  code,  and  insulates 
applications  from  differences  between  display  hardware.  The  server  performs  the  following 
tasks: 

•  Allows  access  to  the  display  by  multiple  clients.  The  server  may  deny  access  from  clients 
running  on  certain  machines. 

•  Interprets  network  messages  from  clients  and  acts  on  them.  These  messages  are  known  as 
requests.  Some  requests  command  the  server  to  do  two-dimensional  drawing,  move  win 
dows,  while  others  ask  the  server  for  information.  Protocol  requests  are  generated  by  cli 
ent  calls  to  Xlib,  either  directly  or  through  Xt  and  other  function  libraries. 

•  Passes  user  input  to  clients  by  sending  network  messages  known  as  events,  which  repre 
sent  key  or  button  presses,  pointer  motion,  and  so  forth.  Events  are  generated  asynchro- 
nously,  and  events  from  different  devices  may  be  intermingled.  The  server  must  pass  the 
appropriate  events  to  each  client. 

•  Maintains  complex  data  structures,  including  windows  and  fonts,  so  that  the  server  can 
perform  its  tasks  efficiently.  Clients  refer  to  these  abstractions  by  ID  numbers.  Server- 
maintained  abstractions  reduce  the  amount  of  data  that  has  to  be  maintained  by  each  cli 
ent  and  the  amount  of  data  that  has  to  be  transferred  over  the  network. 

In  X,  the  term  display  is  often  used  as  a  synonym  for  server,  as  is  the  combined  term  display 
server.  However,  the  terms  display  and  screen  are  not  synonymous.  A  screen  is  the  actual 
hardware  on  which  the  graphics  are  drawn.  A  server  may  control  more  than  one  screen.  For 
example,  a  single  server  might  control  both  a  color  screen  and  a  monochrome  screen,  allow 
ing  a  user  to  debug  an  application  on  both  types  of  screens  without  leaving  seats. 

The  user  programs  displaying  on  the  screen(s)  managed  by  a  server  are  called  its  clients. 
There  may  be  several  clients  connected  to  a  single  server.  Clients  may  run  on  the  same 
machine  as  the  server  if  that  machine  supports  multitasking,  or  clients  may  run  on  other 
machines  in  the  network.  In  either  case,  the  X  Protocol  is  used  by  the  client  to  send  requests 
to  draw  graphics  or  to  query  the  server  for  information,  and  is  used  by  the  server  to  send  user 
input  and  replies  to  information  requests  back  to  the  client.*  All  communication  from  the 


*The  X  Protocol  runs  on  top  of  any  lower-level  network  protocol  that  provides  bidirectional  communication,  and  de 
livers  bytes  unduplicated  and  in  sequence.  TCP/IP  and  DECnet  are  the  only  currently-supported  networks. 
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client  to  the  server  and  from  the  server  to  the  client  takes  place  using  the  X  Protocol.  The 
communication  path  between  a  client  and  the  server  is  called  a  connection. 

It  is  common  for  a  user  to  have  programs  running  on  several  different  hosts  in  the  network, 
all  invoked  from  and  displaying  their  windows  on  a  single  screen  (see  Figure  1-4).  Clients 
running  remotely  can  be  started  from  the  remote  machine,  or  from  the  local  machine  using 
the  network  utilities  rlogin  or  rsh. 


Figure  1-4.  Applications  can  run  on  any  system  across  the  network 

This  use  of  the  network  is  known  as  distributed  processing.  The  most  important  application 
of  this  concept  is  to  provide  graphic  output  for  powerful  systems  that  don't  have  their  own 
built-in  graphics  facilities.  However,  distributed  processing  can  also  help  solve  the  problem 
of  unbalanced  system  loads.  When  one  host  machine  is  overloaded,  the  users  running  clients 
on  that  machine  can  arrange  for  some  of  their  programs  to  run  on  other  hosts.  Eventually, 
there  may  be  automatic  load-balancing  applications,  but  currently,  such  remote  execution  is 
done  manually.  It  is  not  unusual  to  see  users  in  the  X  environment  having  several  xload  load 
monitor  applications  running  on  various  systems  throughout  the  network  but  displaying  on 
their  screen,  so  that  they  can  see  the  balance  of  loads  throughout  the  network. 
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Before  leaving  the  subject  of  servers  and  clients,  we  should  mention  PC  servers  and  X  termi 
nals.  Software  is  available  that  allows  various  types  of  PCs  to  operate  as  X  servers.*  X  ter 
minals  are  special-purpose  devices  designed  to  run  just  an  X  server,  and  to  connect  to  remote 
systems  over  a  local  area  network.  PC  servers  and  X  terminals  are  the  least  expensive  way  to 
provide  an  X  screen  for  a  user.  Since  most  PCs  use  single-tasking  operating  systems,  they 
can't  run  any  clients  at  the  same  time  as  the  server.  Therefore,  they  too  require  a  network 
adapter  to  connect  to  another  system  where  clients  are  run. 

X  terminals  and  PC  servers  both  demonstrate  the  strength  of  X's  client-server  model.  Even 
though  PCs  and  X  terminals  aren't  able  to  do  multitasking  on  their  own,  they  give  the  user 
the  effect  of  multitasking  workstations,  because  they  can  interact  simultaneously  with  several 
clients  running  on  remote  multitasking  systems. 


1.2  The  Software  Hierarchy 

This  book  is  about  writing  client  applications  for  the  X  Window  System,  in  C,  using  the  Xt 
Intrinsics  library  and  a  set  of  widgets.  This  is  only  one  of  the  many  ways  to  write  X  applica 
tions,  because  X  is  not  restricted  to  a  single  language  or  operating  system.  The  only  require 
ment  of  an  X  application  is  that  it  generate  and  receive  X  protocol  messages.  However,  using 
the  Xt  Intrinsics  and  a  widget  set  is,  and  is  expected  to  continue  to  be,  the  most  common  way 
of  writing  applications  for  several  reasons:  it  is  quite  powerful;  it  results  in  applications  that 
cooperate  well  with  other  X  applications;  and  the  C  language  is  so  widely  available. 

Figure  1-5  shows  the  layering  of  software  in  an  application  that  uses  the  Xt  Intrinsics  and  a 
widget  set  Notice  that  the  Intrinsics  are  based  upon  Xlib,  the  lowest-level  C-language  inter 
face  to  X.  Xlib  provides  full  access  to  the  capabilities  of  the  X  protocol,  but  does  little  to 
make  programming  easier.  It  handles  the  interface  between  an  application  and  the  network, 
and  includes  some  optimizations  that  encourage  efficient  network  usage. 

Xt  is  built  upon  Xlib.  The  purpose  of  Xt  is  to  provide  an  object-oriented  layer  that  supports 
the  user-interface  abstraction  called  a  widget  A  widget  is  a  reusable,  configurable  piece  of 
code  that  operates  independently  of  the  application  except  through  prearranged  interactions. 
A  widget  set  is  a  collection  of  widgets  that  provide  commonly  used  user-interface  compo 
nents  tied  together  with  a  consistent  appearance  and  user  interface  (also  called  look  and  fee  I). 
There  are  several  different  widget  sets  from  various  vendors  that  are  designed  to  work  with 
Xt.  The  use  of  widgets  separates  application  code  from  user-interface  code,  and  provides 
ready-to-use  user-interface  components  such  as  buttons  and  scrollbars.  Xt,  widgets,  and 
widget  sets  are  described  in  much  more  detail  in  Chapter  2,  Introduction  to  the  X  Toolkit. 

In  this  book,  we'll  refer  to  the  combination  of  the  Xt  Intrinsics  and  one  widget  set  as  the  X 
Toolkit  or  just  the  Toolkit.  When  referring  to  the  Xt  Intrinsics  layer  alone,  we'll  useXY,  or  the 
Intrinsics. 


*Companies  such  as  Graphics  Software  Systems,  Interactive  Systems,  and  Locus  Computing  offer  server  implemen 
tations  for  IBM-compatible  PCs.  White  Pine  Software  offers  an  X  server  that  runs  under  Multifinder  on  the  Macin 
tosh.  An  Amiga  server  is  available  from  GfxBase/Boing.  X  terminals  are  available  from  Visual  Technology,  NCR, 
Network  Computing  Devices  (NCD),  Tektronix,  Graphon  Corp,  and  others.  The  number  of  X  products  on  the  market 
is  growing  rapidly. 
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Figure  1-5.  The  software  architecture  ofXt  Intrinsics-based  applications 

Applications  often  need  to  call  Xlib  directly  to  accomplish  certain  tasks  such  as  drawing.  Xt 
does  not  provide  its  own  graphics  calls,  nor  does  it  provide  access  to  every  X  protocol  fea 
ture.  This  book  will  describe  the  features  of  Xlib  that  you  may  need  from  a  Xt  application, 
but  it  will  not  repeat  the  detailed  description  of  Xlib  programming  found  in  Volume  One, 
Xlib  Programming  Manual.  You  will  find  Volume  One  and  Volume  Two  (Xlib  Reference 
Manual)  invaluable  when  you  need  to  make  Xlib  calls. 

Xlib,  Xt,  and  several  widget  sets  are  available  on  MIT's  public  software  distribution.*  The 
darkly  shaded  areas  of  Figure  1-5  indicate  interfaces  that  are  exclusive  standards  of  the  X 
Consortium.  That  Xlib  is  an  exclusive  standard  means  that  computer  manufacturers  wishing 
to  comply  with  the  X  Consortium  standard  must  offer  Xlib  and  cannot  offer  any  other  low- 
level  X  interface  in  C.  The  lightly  shaded  areas  (such  as  the  Xt  Intrinsics)  are  nonexclusive 
standards — vendors  are  required  to  provide  Xt  but  are  also  allowed  to  provide  other  toolkit- 
level  layers  for  the  C  language.  For  example,  Sun  and  AT&T  will  offer  Xt,  but  will  also  offer 


*The  Motif  and  OPEN  LOOK  toolkits  are  not  on  the  Release  3  or  Release  4  distributions  from  MIT,  but  they  are  avail 
able  for  minimal  cost  from  the  vendors  themselves  (OSF  and  AT&T  or  Sun  respectively.) 
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XView  as  an  alternate  C-language  toolkit-level  layer.  XView  was  originally  designed  for 
porting  existing  Sun  View™  applications  to  X,  but  it  can  also  be  used  for  writing  new  appli 
cations. 

X  software  is  unlike  many  other  window  systems  in  that  it  was  designed  to  provide  mech 
anism  without  mandating  any  certain  style  of  user  interface.  In  the  words  of  its  designers,  X 
provides  "mechanism  without  policy."  The  Xlib  and  Xt  layers  are  standard  because  they  can 
support  any  kind  of  interface.  It  is  the  widget  set  that  actually  imposes  user-interface  con 
ventions,  and  it  is  this  layer  for  which  no  standard  has  (yet)  been  considered  by  the  X  Con 
sortium.  However,  because  there  is  a  strong  need  in  the  market  for  one  or  two  standard 
widget  sets  that  provide  consistent  appearance  and  user-interface  conventions,  it  is  likely  that 
one  or  two  widget  sets  will  emerge  as  de  facto  standards  in  the  near  future. 

It  is  important  to  note  that  the  X  Consortium  standards  for  Xlib  and  Xt  define  the  program 
ming  interface  to  each  library  (often  referred  to  as  the  Application  Programmer's  Interface, 
or  API),  not  the  underlying  code.  That  means  that  vendors  are  allowed  to  modify  or  rewrite 
the  code  to  gain  the  best  performance  from  their  particular  system,  as  long  as  they  keep  the 
programming  interface  the  same.  To  you,  the  application  writer  and  user  of  the  Intrinsics, 
this  means  that  you  must  always  rely  on  documented  behavior  if  you  want  your  application  to 
run  on  different  systems.  You  must  avoid  accessing  private  structures,  because  they  may  be 
different  in  another  vendor's  release  of  the  library,  or  may  be  changed  in  a  future  release  of 
X. 


1.3  Event-driven  Programming 

Programming  a  graphically-based  window  system  is  fundamentally  different  from  standard 
procedural  programming.  In  traditional  character-based  interfaces,  once  the  application 
starts,  it  is  always  in  control.  It  knows  just  what  kind  of  input  it  will  allow,  and  may  define 
exclusive  modes  to  limit  that  input.  For  example,  the  application  might  ask  the  user  for  input 
with  a  menu,  and  use  the  reply  to  go  down  a  level  to  a  new  menu,  where  the  actions  that  were 
possible  at  the  previous  level  are  no  longer  available.  Or  a  text  editor  may  operate  in  one 
mode  in  which  keyboard  input  is  interpreted  as  editor  commands,  and  another  in  which  it  is 
interpreted  as  data  to  be  stored  in  an  editor  buffer.  In  any  case,  only  keyboard  input  is 
expected. 

In  a  window  system,  by  contrast,  multiple  graphic  applications  may  be  running  simulta 
neously.  In  addition  to  the  keyboard,  the  user  can  use  the  pointer  to  select  data,  click  on  but 
tons  or  scrollbars,  or  change  the  keyboard  focus  from  one  application  to  another.  Except  in 
special  cases  (for  example,  where  a  "dialog  box"  will  not  relinquish  control  of  the  keyboard 
focus  until  the  user  provides  some  necessary  information),  applications  are  modeless — the 
user  can  suddenly  switch  from  the  keyboard  to  the  mouse,  or  from  one  application  area  to 
another.  Furthermore,  as  the  user  moves  and  resizes  windows  on  the  screen,  application  win 
dows  may  be  obscured  or  redisplayed.  The  application  must  be  prepared  to  respond  to  any 
one  of  many  different  events  at  any  time. 

An  X  event  is  a  data  structure  sent  by  the  server  that  describes  something  that  just  happened 
that  may  be  of  interest  to  the  application.  There  are  two  major  categories  of  events:  user 
input  and  window  system  side  effects.  For  example,  the  user  pressing  a  keyboard  key  or 
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clicking  a  mouse  button  generates  an  event;  a  window  being  moved  on  the  screen  also  gener 
ates  events — possibly  in  other  applications  as  well  if  the  movement  changes  the  visible  por 
tions  of  their  windows.  It  is  the  server's  job  to  distribute  events  to  the  various  windows  on 
the  screen. 

Event-driven  window  programming  reduces  modes  to  a  minimum,  so  that  the  user  does  not 
need  to  navigate  a  deep  menu  structure  and  can  perform  any  action  at  any  time.  The  user,  not 
the  application,  is  in  control.  The  application  simply  performs  some  setup  and  then  goes  into 
a  loop  from  which  application  functions  may  be  invoked  in  any  order  as  events  arrive. 

1.4  The  Window  Manager 

Because  multiple  client  applications  can  be  running  simultaneously,  rules  must  exist  for  arbi 
trating  conflicting  demands  for  input.  For  example,  does  keyboard  input  automatically  go  to 
whichever  window  the  pointer  is  in,  or  must  the  user  explicitly  select  a  window?  How  does 
the  user  move  or  resize  windows? 

Unlike  most  window  systems,  X  itself  makes  no  rules  about  this  kind  of  thing.  Instead,  there 
is  a  special  client  called  the  window  manager  that  manages  the  positions  and  sizes  of  the 
main  windows  of  applications  on  a  server's  display.  The  window  manager  is  just  another  cli 
ent,  but  by  convention  it  is  given  special  responsibility  to  mediate  competing  demands  for  the 
physical  resources  of  a  display,  including  screen  space,  color  resources,  and  the  keyboard. 
The  window  manager  allows  the  user  to  move  windows  around  on  the  screen,  resize  them, 
and  usually  start  new  applications.  The  window  manager  also  defines  much  of  the  visible 
behavior  of  the  window  system,  such  as  whether  windows  are  allowed  to  overlap  or  are  tiled 
(side  by  side),  and  whether  the  keyboard  keyboard  focus  simply  follows  the  pointer  from 
window  to  window,  or  whether  the  user  must  click  a  pointer  button  in  a  window  to  change 
the  keyboard  focus. 

Applications  are  required  to  give  the  window  manager  certain  information  to  help  it  mediate 
competing  demands  for  screen  space  or  other  resources.  For  example,  an  application  speci 
fies  its  preferred  size  and  size  increments.  These  are  known  as  window  manager  hints 
because  the  window  manager  is  not  required  to  honor  them.  The  Toolkit  provides  an  easy 
way  for  applications  to  set  window  manager  hints. 

The  conventions  for  interaction  with  the  window  manager  and  with  other  clients  have  been 
standardized  by  the  X  Consortium  as  of  July  1989  in  a  manual  called  the  Inter-Client  Com 
munication  Conventions  Manual  (ICCCM  for  short).  The  ICCCM  defines  basic  policy  inten 
tionally  omitted  from  X  itself,  such  as  the  rules  for  transferring  data  between  applications 
(selections),  for  transferring  keyboard  focus,  for  installing  colormaps,  and  so  on. 

As  long  as  applications  and  window  managers  follow  the  conventions  set  out  in  the  ICCCM, 
applications  created  with  different  toolkits  will  be  able  to  coexist  and  work  together  on  the 
same  server.  Toolkit  applications  should  be  immune  to  the  effects  of  changes  from  earlier 
conventions  because  the  conventions  are  implemented  by  code  hidden  in  a  standard  widget 
called  Shell.  However,  you  should  be  aware  that  some  older  applications  and  window  man 
agers  do  not  play  by  the  current  rules. 
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1 .5  Extensions  to  X 

X  is  also  extensible.  The  code  includes  a  defined  mechanism  for  incorporating  extensions,  so 
that  vendors  aren't  forced  to  modify  the  existing  system  in  incompatible  ways  when  adding 
features.  An  extension  requires  an  additional  piece  of  software  on  the  server  side  and  an 
additional  library  at  the  same  level  as  Xlib  on  the  client  side.  After  an  initial  query  to  see 
whether  the  server  portion  of  the  extension  software  is  installed,  these  extensions  are  used 
just  as  Xlib  routines  and  perform  at  the  same  level. 

Among  the  extensions  currently  being  developed  are  support  for  2-D  spline  curves,  for  3-D 
graphics,  and  for  display  PostScript™.  These  extensions  can  be  used  in  Toolkit  applications 
just  as  Xlib  can. 
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Introduction  to  the  X  Toolkit 


This  chapter  provides  a  conceptual  introduction  to  the  X  Toolkit,  followed  by  a 
practical  tutorial  that  starts  with  the  most  fundamental  toolkit  program,  a  "hello 
world"  type  application  consisting  of  only  a  single  widget.   This  application  is 
successively  refined  until  the  major  elements  of  any  X  Toolkit  program  have 
been  introduced. 
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Building  applications  for  a  graphical  user  interface  using  a  low-level  programming  library 
such  as  Xlib  requires  much  sophisticated  programming.  To  simplify  development,  each  of 
the  user-interface  elements  of  a  graphical  application — scrollbars,  command  buttons,  dialog 
boxes,  pop-up  or  pull-down  menus  (everything  but  the  main  application  window)  should  ide 
ally  be  available  ready-made,  so  the  programmer  need  only  integrate  them  with  the  applica 
tion  code. 

The  purpose  of  the  X  Toolkit  is  to  provide  such  a  simplified  approach  to  graphical  user- 
interface  programming.  However,  in  keeping  with  the  X  philosophy  of  "mechanism,  not  pol 
icy,"  the  designers  of  the  X  Toolkit  didn't  develop  a  fixed  set  of  components  with  a  prede 
fined  look  and  feel.  Instead,  they  created  a  general  mechanism  for  producing  reusable  user- 
interface  components,  which  can  be  either  built  by  the  application  programmer  himself,  or 
constructed  by  lower-level  "object  programmers"  and  collected  in  libraries  for  application 
use. 

The  heart  of  the  Toolkit  is  a  C  library  called  Xt,  also  known  as  the  X  Toolkit  Intrinsics.  Xt 
provides  routines  for  both  creating  and  using  user-interface  components  called  widgets.  A 
typical  application  will  use  Xt  along  with  a  library  of  pre-built  widgets  (a  widget  set)  such  as 
menus,  dialog  boxes,  scrollbars,  command  buttons,  and  so  forth,  working  together  to  provide 
a  consistent  application  "look  and  feel." 


2.1   Programming  with  Widgets 

The  simplest  way  to  understand  the  role  of  widgets  in  the  X  Toolkit  is  to  look  at  a  hypotheti 
cal  application,  such  as  the  one  shown  in  Figure  2-1. 

If  you  are  at  all  familiar  with  graphical  applications,  you  will  recognize  many  of  the  widgets 
called  out  in  the  figure  as  standard  user-interface  elements: 

•  Command  buttons,  which  initiate  some  application  action  when  clicked  on  with  the 
mouse. 

•  A  scrollbar,  which  allows  the  user  to  scroll  the  data  visible  in  an  associated  display  win 
dow.  (The  position  of  a  "thumb"  within  the  scrollbar  indicates  the  position  of  the  visible 
data  within  a  larger  data  buffer,  and  lets  the  user  change  the  current  position  in  the  buffer 
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Figure  2-1.  A  widget-based  application 

by  dragging  the  thumb  with  the  mouse.  Widget  sets  vary  in  their  term  for  the  scrollbar 
thumb.) 

•  A  data  entry  area,  in  which  the  user  can  type  information  requested  by  the  application. 

There  are  other  widgets  in  the  application  that  might  not  be  as  obvious: 

•  Composite  widgets,  which  are  used  to  contain  other  widgets.  In  all  widget  sets,  there  are 
special  classes  of  widgets  whose  function  is  to  manage  the  position  (and  possibly  the 
size)  of  the  child  widgets  they  contain. 

Composite  widgets  are  an  important  part  of  any  widget  set,  since  they  insulate  the  appli 
cation  programmer  from  having  to  place  each  widget  individually,  or  from  having  to 
reposition  or  resize  various  widgets  when  the  application  is  resized  by  the  user.  Compos- 
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ite  widgets  automatically  adjust  the  layout  of  their  children  when  child  widgets  are  added 
or  removed. 

Shell  widgets.  In  any  X  Toolkit  application,  a  special  widget  called  a  Shell  widget  is 
created  by  the  call  to  initialize  the  Toolkit  This  widget  is  used  as  the  parent  of  all  other 
application  widgets  (with  the  exception  of  pop  ups,  which  receive  their  own  transient 
Shell  widget  as  a  parent),  and  includes  special  functionality  that  allows  it  to  interact  with 
the  window  manager.  The  Shell  widget  is  invisible,  since  it  is  overlaid  by  the  main 
widget  of  the  application  (typically  a  composite  widget),  which  is  exactly  the  same  size.* 

A  special-purpose  application  window.  Most  applications  have  at  least  one  window  that 
has  unusual  characteristics  not  supported  by  an  existing  widget.  For  example,  in  our 
hypothetical  application,  the  main  application  window  is  used  to  graph  the  performance 
of  a  stock  portfolio. 

There  are  two  ways  to  implement  such  windows.  You  can  add  functionality  to  an  exist 
ing  widget  (usually  what  is  called  a  Core  widget)  by  adding  actions  as  described  and 
demonstrated  in  Chapter  4,  An  Example  Application,  or  you  can  write  your  own  widget, 
as  described  beginning  in  Chapter  5,  Inside  a  Widget.  As  you  will  see,  after  you  have 
written  the  application  code  to  operate  the  special-purpose  window,  making  a  widget  that 
does  the  same  thing  is  mostly  a  matter  of  rearranging  the  code  and  changing  variable 
names.  Placing  code  into  a  widget  gives  you  easier  access  to  the  configurability  features 
of  Xt,  and  neatly  packages  up  the  code  to  operate  the  special  window. 

A  pop-up  dialog  box.  A  pop  up  is  a  widget  that  appears  temporarily  on  the  screen,  until 
the  user  provides  a  certain  kind  of  input.  Pop  ups  are  usually  invisible  when  the  applica 
tion  starts  up.  Using  Xt,  applications  create  pop  ups  very  much  like  permanent  widgets. 
The  only  difference  is  that  a  special  kind  of  Shell  widget  called  a  pop-up  shell  needs  to  be 
created  as  the  parent  of  the  widget  to  be  popped  up.  Many  types  of  menus  and  dialog 
boxes  (also  referred  to  as  "notices")  are  intended  to  be  used  as  pop  ups. 


2.1 .1    Contents  of  a  Widget  Set 

Shell  widgets,  and  a  few  other  base  widget  classes  (Core,  Composite,  and  Constraint)  that  are 
used  to  build  more  complex  widgets,  are  defined  by  Xt.  The  special-purpose  application  win 
dow  is  written  by  the  application  programmer.  All  of  the  other  widgets  shown  in  Figure  2-1 
are  from  the  Athena  widget  set,  developed  at  MIT. 

The  Xaw  library  in  the  standard  X  distribution  contains  the  Athena  widget  set  This  book 
provides  examples  using  the  Athena  widgets  because  they  are  universally  available,  and 
because  the  techniques  for  using,  modifying,  and  creating  widgets  are  the  same,  regardless  of 
which  widget  set  you  use.  However,  the  Athena  widget  set  was  not  intended  to  be  com 
plete — it  was  built  mainly  for  testing  and  demonstrating  the  Intrinsics.  Furthermore,  the 


*The  Shell  widget  is  actually  a  type  of  composite  widget,  which  is  designed  to  have  only  one  child  widget.  Its  layout 
policy  is  extremely  simple.  It  just  makes  its  child  widget  exactly  the  same  size  as  itself. 
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Athena  set  does  not  have  a  particularly  attractive  appearance.  For  these  reasons,  we  suggest 
that  serious  application  development  efforts  should  begin  with  a  commercial  widget  set 

Two  commercial  widget  sets  that  are  easily  available  and  quite  complete  are  OSF's  Motif 
and  AT&T's  OPEN  LOOK  widgets.  Both  Motif  and  OPEN  LOOK  contain  menus,  scrollbars, 
command  buttons,  dialog  boxes,  and  a  wide  variety  of  composite  widgets.  Both  have  an 
attractive  appearance  and  consistent,  well  defined  user-interface  conventions.  Each  comes 
with  a  style  guide  that  contains  suggestions  for  designing  applications  to  blend  in  well  with 
other  applications  using  that  widget  set 

Appendix  A,  OPEN  LOOK  and  Motif,  describes  these  widget  sets. 

2.1.2   Widget  Classes  and  Instances 

A  widget  library  defines  classes  of  widgets.  Each  class  has  unique  characteristics  shared 
with  all  other  members  of  that  class,  but  distinct  from  other  classes.  Command  is  a  class  of 
widget,  as  are  Box,  Label,  Scroll,  and  the  other  Athena  widgets  shown  in  our  hypothetical 
application.  Each  time  you  create  a  widget,  you  create  an  instance  of  one  of  these  predefined 
classes.  For  example,  you  might  create  several  Command  widgets,  each  with  a  unique  name, 
containing  a  unique  text  label,  and  each  invoking  different  application  code  when  it  is 
clicked  on. 

Widget  characteristics  can  be  inherited  from  other,  more  basic  classes  of  widgets.  Inheri 
tance  means  that  a  new  class  of  widget  has  to  define  only  its  own  unique  features,  and  need 
not  re-implement  those  common  to  all  widgets,  or  already  implemented  by  an  existing  super 
class.  All  classes  exist  in  a  hierarchy,  which  defines  from  which  other  classes  each  class 
inherits  features.  (Note  that  the  class  hierarchy  is  completely  different  from  the  parent-child 
relationship  of  widget  instances  you  create  in  an  application.  The  class  hierarchy  of  a  partic 
ular  widget  class  is  fixed,  while  the  instance  hierarchy  is  set  differently  in  every  application.) 

Figure  2-2  shows  the  class  inheritance  hierarchy  for  the  Athena  Widgets.  Classes  defined  by 
Xt  (which  are  the  same  for  all  widget  sets)  are  shaded  gray.* 


*Nole  that  the  X  Toolkit  supports  only  single  inheritance.  That  is,  characteristics  can  be  inherited  directly  from  only 
one  superclass  (though  that  superclass  may  itself  have  inherited  characteristics  from  prior  superclasses). 
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Figure  2-2.  Inheritance  among  the  Athena  widgets 

The  Core  widget  class,  defined  by  the  Intrinsics,  is  the  root  of  the  hierarchy,  from  which  all 
other  classes  are  descended.  The  Core  class  defines  characteristics  common  to  all  widgets, 
such  as  size  and  position. 

The  Athena  Simple  widget  class  inherits  basic  widget  features  from  Core  and  adds  a  few 
minor  features  of  its  own  (for  example,  the  ability  to  change  the  cursor  shape  when  it  enters 
the  window).  The  Label  widget  in  turn  adds  the  ability  to  print  a  string,  and  mechanisms  for 
changing  the  font  and  placement  of  the  string.  Command  then  inherits  features  from  Label 
(including  those  already  inherited  from  Core  and  Simple)  and  adds  more  features  (the  ability 
to  accept  user  input,  and  to  highlight  the  button).  Command  is  known  as  a  subclass  of  Label, 
and  Label  is  the  superclass  of  Command.  In  general,  lower  classes  in  the  hierarchy  have 
more  features. 

As  you  can  see  from  Figure  2-2,  Text,  List,  Scroll,  and  Grip,  like  Label,  are  simple  widgets 
subclassed  directly  from  Core.  Command  is  a  refinement  of  Label.  The  Text  widget  provides 
a  ready-built,  configurable  text  editor.  List  displays  a  list  of  strings,  which  can  be  selected 
individually,  and  passed  to  an  application  function.  (For  example,  this  widget  might  be  used 
to  implement  a  file  selection  box  from  which  the  user  might  select  which  file  to  open.) 
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Scroll  widgets  are  designed  to  be  attached  to  other  windows,  and  to  provide  a  mechanism  by 
which  the  user  can  scroll  the  data  in  a  window  by  dragging  or  clicking  in  the  scrollbar.  A 
Grip  is  a  small  solid  box  used  for  resizing  panes  in  a  Vpaned  widget  (see  Figure  2-3). 

The  Vpaned  widget  manages  a  series  of  vertical  panes,  which  have  the  constraint  that  they 
can  only  be  resized  in  the  vertical  direction,  by  using  the  pointer  to  drag  Grip  widgets  pro 
vided  for  that  purpose.  Vpaned  is  useful  for  applications  such  as  xmh,  the  X  mail  handler, 
that  display  data  in  several  different  windows  simultaneously. 

Figure  2-3  shows  a  VPaned  widget 
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Figure  2-3.  An  Athena  VPaned  widget  (paned  in  R4) 

Form  allows  the  position  of  its  children  to  be  specified  relative  either  to  each  other  or  to  fixed 
points  in  the  Form  parent  Children  are  thus  constrained  always  to  have  the  same  relative 
position  in  the  parent  even  when  it  is  resized. 

Dialog  is  a  subclass  of  Form  that  has  been  given  specific  children:  a  Label,  which  is  used  for 
printing  a  message,  an  optional  Text  widget  for  data  entry,  and  two  command  widgets,  for 
confirming  or  cancelling  the  action  suggested  by  the  dialog. 

Figure  2-4  shows  a  Dialog  widget 
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Figure  2-4.  An  Athena  Dialog  widget 

The  Composite  class  adds  geometry-management  capabilities  to  the  basic  characteristics 
defined  by  Core.  Box  is  a  subclass  of  Composite  that  is  mainly  intended  to  manage  a  group 
of  similarly-sized  Command  widgets.  Viewport  is  a  composite  widget  that  provides  a  main 
window  and  horizontal  and  vertical  scrollbars.  Figure  2-5  shows  a  Viewport  widget  manag 
ing  a  List  widget  and  a  Scroll  widget 
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Figure  2-5.  A  Viewport  widget 


viewport  widget 


Shell  is  a  special  class  of  Composite  widget  designed  for  interaction  with  the  window  man 
ager. 
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Most  applications  use  a  TopLevel  shell  for  their  main  window;  pop  ups  use  either  an  Over- 
RideShell  or  a  TransientShell.  (See  Chapter  12,  Menus,  Gadgets,  and  Cascaded  Pop  Ups  for 
more  information  on  Shell  widget  classes.) 

Constraint  is  a  further  refinement  of  Composite  that  allows  the  application  or  the  user  to  sup 
ply  instructions  about  how  the  size  and  position  of  each  child  should  be  managed. 

The  Athena  widgets  are  described  in  Volume  Five,  X  Toolkit  Intrinsics  Reference  Manual. 

New  widgets  can  be  subclassed  by  the  widget  programmer  directly  from  Core,  Composite,  or 
Constraint,  or  can  be  subclassed  from  an  existing  widget  in  any  widget  set  that  has  some,  but 
not  all,  of  the  desired  behavior.  For  example,  it  is  easy  to  imagine  creating  subclasses  of 
Form  to  provide  other  types  of  preconfigured  dialog  boxes  or  data  entry  screens. 

As  long  as  appropriate  widget  classes  are  available,  the  application  programmer  needs  to 
know  little  or  nothing  about  widget  internals.  He  can  use  existing  widgets  for  most  purposes. 

2.1.3   Widget  Configurability  with  Resources 

To  serve  their  purpose  as  reusable  user-interface  components,  widgets  must  be  highly  confi 
gurable.  For  example,  an  application  programmer  must  be  able  to  define  not  only  a  separate 
label  for  each  Command  widget,  but  also  the  application  function  that  is  invoked  when  the 
button  is  clicked.  The  programmer  will  also  want  to  let  the  user  define  additional  attributes 
such  as  font  and  color. 

To  support  this  degree  of  configurability,  widget  classes  can  declare  variables  as  named 
resources  of  the  widget  The  application  can  pass  the  value  of  widget  resources  as  arguments 
to  the  call  to  create  a  widget  instance,  or  can  set  them  after  creation  using  the  Intrinsics  call 
xt  Set  Value  s.  In  addition,  though,  as  an  application  starts  up,  a  part  of  Xlib  called  the 
resource  manager  reads  configuration  settings  placed  in  a  series  of  interrelated  ASCE  files  by 
the  user  and/or  the  application  developer,  and  Xt  automatically  uses  this  information  to  con 
figure  the  widgets  in  the  application.  The  collection  of  resource  name- value  pairs  contained 
in  the  various  resource  files  and  set  directly  by  the  application  is  collectively  referred  to  as 
the  resource  database. 

Figure  2-6  shows  several  Label  widgets  configured  with  different  resource  settings,  to  show 
you  how  radically  the  appearance  of  even  such  a  simple  widget  can  be  altered.  Note  that  the 
widget's  input  characteristics  can  also  be  configured. 

The  resource  manager  provides  a  very  flexible  mechanism  for  generalizing  the  behavior  of 
widgets.  The  application  developer  can  "hardcode"  the  value  of  resources  that  cannot  be 
changed  without  crippling  the  widget  or  application,  and  can  establish  reasonable  defaults 
for  the  rest,  so  that  the  user  can  configure  all  nonessential  aspects  of  application  appearance 
and  behavior. 

Note  that  the  term  resource  is  used  somewhat  ambiguously  in  X.  First,  in  the  original  docu 
mentation  for  Xlib  and  the  X  protocol,  various  data  structures  that  are  maintained  by  the 
server  and  identified  to  clients  only  by  an  integer  ID  are  referred  to  as  resources.  These  data 
structures  include  windows,  bitmaps,  fonts,  and  so  forth. 
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Figure  2-6.  Several  Label  widgets  configured  using  resources 

Second,  the  term  is  commonly  used  to  refer  both  to  a  widget  variable  publicly  declared  as  a 
widget  resource,  and  to  the  name-value  pairs  in  the  resource  database.  In  this  book,  we  will 
use  the  term  resource  to  refer  to  the  the  actual  variable  and  its  current  value  in  a  widget 
instance,  and  the  term  resource  setting  to  refer  to  a  name-value  pair  in  the  database.  The  two 
are  closely  related,  but  may  not  be  identical.  For  example,  separate  settings  for  the  same 
resource  may  be  requested  in  an  application-defaults  file  and  in  an  individual  user-preference 
file.*  Furthermore,  the  value  of  a  resource  may  be  set  on  the  fly  by  a  call  to  xt  SetValues, 
but  this  value  is  never  saved  in  the  resource  database.  (This  value  can  be  retrieved  from 
within  a  widget  or  application  by  a  call  to  xtGetValues.) 


2.1.4   Widget  Independence 

Each  widget  is,  to  a  large  degree,  independent  of  the  application.  Xt  dispatches  events  to  a 
widget,  which  performs  the  appropriate  actions  according  to  the  design  of  its  class,  without 
application  help.  For  example,  widgets  redraw  themselves  automatically  when  they  become 
exposed  after  being  covered  by  another  window.!  Widgets  also  handle  the  consequences 


*There  are  several  possible  sources  of  resource  settings.  Which  will  actually  take  effect  is  determined  by  rules  of 
precedence  that  are  described  (along  with  the  various  sources  of  resource  settings)  in  Chapter  9. 
fRedrawing  is  necessary  because  only  the  visible  contents  of  X  windows  are  maintained  by  the  X  server.  When  one 
window  is  obscured  by  another,  the  contents  of  the  obscured  window  are  lost,  and  must  be  redrawn  when  it  is  expo 
sed.  X  clients  are  responsible  for  redrawing  the  contents  of  their  windows  when  this  happens.  Fortunately,  Xt  auto 
matically  redraws  correctly  written  widgets  at  the  appropriate  times  so  that  your  application  doesn't  have  to  worry 
about  it. 
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when  the  values  of  their  resources  are  changed.  An  instance  of  Label,  for  example,  does  not 
depend  on  the  application  that  created  it  to  determine  its  size.  By  default,  Label  will  choose 
a  size  large  enough  to  accommodate  the  current  string  in  the  current  font.  If  the  application 
changes  the  text  or  font  in  the  Label  widget  with  a  call  to  xtSetValues,  the  Label  widget 
itself  will  attempt  to  keep  its  own  window  large  enough  to  accommodate  the  current  string. 
(Of  course,  if  necessary,  the  application  can  also  explicitly  choose  the  Label  widget's  size.) 
When  the  application  tells  a  Label  widget  what  font  to  display  its  string  in,  the  widget  knows 
how  to  load  a  new  font,  recalculate  its  own  size,  and  redraw  its  string — the  application 
doesn't  have  to  micro-manage  any  of  this.  The  application  simply  sets  the  font  resource  of 
the  widget,  and  the  widget  does  the  rest. 

Figure  2-7  and  Figure  2-8  illustrate  how  a  widget  operates  independently  of  the  application 
and  how  xt  Set  Values  lets  the  application  set  how  a  widget  operates  itself. 
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Figure  2-7.  Widgets  operate  independently  of  the  application 
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...but  the  application  can  change  various  characteristics  of  the 
widget  with  XtSetValues 


Figure  2-8.  XtSetValues  lets  the  application  set  how  a  widget  will  operate  itself 

2.1.5   Widget-Application  Interaction 

In  the  other  direction,  widgets  are  designed  to  let  the  user  control  the  application.  Therefore, 
widgets  have  the  ability  to  invoke  certain  sections  of  application  code — elements  of  the 
application's  own  choosing.  Again,  though,  widgets  will  operate  fine  without  invoking  any 
application  code,  but  if  they  don't  invoke  any,  they  won't  do  anything  for  the  user. 

One  way  that  the  application  arranges  for  widgets  to  invoke  application  code  is  by  register 
ing  application  functions  with  Xt.  Once  the  application  is  running,  Xt  will  call  these  func 
tions  in  response  to  some  occurrence  in  the  widget.  For  example,  a  Command  widget  usually 
invokes  an  application  function  when  the  user  clicks  on  the  widget.  (Thus,  the  widget 
labeled  "Quit"  might  invoke  the  code  that  exits  the  application.)  Or  the  Scroll  widget  noti 
fies  the  application  when  the  user  has  moved  the  thumb,  by  calling  a  function  that  the  appli 
cation  has  registered  with  the  widget  for  that  purpose.  Figure  2-9  and  Figure  2-10  illustrate 
how  an  application  registers  a  function  during  the  startup  phase,  and  how  Xt  then  calls  the 
function  during  the  event-loop  phase  in  response  to  a  particular  occurrence  in  the  widget. 
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...  and  the  application  can  provide  and  register  callback  or  action 
functions  with  the  widget ... 


Figure  2-9.  Application  registers  a  function  with  Xt  during  startup  phase 

There  are  three  separate  mechanisms  that  can  be  used  to  link  widgets  and  application  func 
tions:  callbacks,  actions,  and  event  handlers. 

Generally  speaking,  a  widget  expecting  to  interact  with  an  application  will  declare  one  or 
more  callback  lists  as  resources;  the  application  adds  functions  to  these  callback  lists,  which 
will  be  invoked  whenever  the  predefined  callback  conditions  are  met.  Callback  lists  are 
resources,  so  that  the  application  can  set  or  change  the  function  that  will  be  invoked. 

Callbacks  are  not  necessarily  invoked  in  response  to  any  event;  a  widget  can  call  the  speci 
fied  routines  at  any  arbitrary  point  in  its  code,  whenever  it  wants  to  provide  a  "hook"  for 
application  interaction.  For  example,  all  widgets  provide  a  destroyCallback  resource 
to  allow  applications  to  interpose  a  routine  to  be  executed  when  the  widget  is  destroyed. 


26 


X  Toolkit  Intrinsics  Programming  Manual 


Widget        I 


callback  routines 
or  action  routines 
U  invoked 


Application  Code  I 


Xt 

Intrinsics 
routines 


...  which  the  widget  will  call  when  certain  events  occur.  The 
widget  gives  control  back  to  the  application  for  the  duration  of 
the  callback  or  action  routine. 


Figure  2-10.  Xt  calls  the  function  during  the  event-loop  phase  in  response  to  an  occurrence 

However,  callbacks  are  often  invoked  by  widgets  from  within  actions,  which  are  event- 
driven.  Action  routines  are  called  directly  by  Xt  in  response  to  events  specified  in  a  trans 
lation  table.  The  Xt  Translation  Manager  supports  a  high-level,  event-specification  syntax, 
which  allows  easy  specification  of  complicated  event  sequences  (such  as  double-  or  triple- 
clicks,  or  key-  and  button-press  combinations)  as  the  trigger  for  actions.  Furthermore,  the 
translation  table  is  a  resource,  allowing  the  application  developer  or  the  user  to  configure  the 
events  that  will  invoke  a  given  widget  action. 

Actions  may  be  internal  to  the  widget  and  require  no  interaction  with  the  application.  (For 
example,  in  the  Athena  Text  widget,  all  editing  operations  are  carried  out  entirely  by  the 
widget,  using  functions  defined  as  actions.  The  only  role  required  of  the  application  is  to 
read  and  write  files.)  However,  an  application  can  also  add  actions  to  a  widget,  which  can 
function  in  much  the  same  way  as  callbacks,  but  without  the  widget  class  having  made  provi 
sion  for  them. 
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The  purpose  of  a  well-designed  widget  set  is  to  implement  a  particular  user  interface,  which 
provides  conventions  designed  to  make  all  applications  operate  in  the  same  way.  A  widget's 
callbacks  are  often  designed  to  support  the  intended  use  of  the  widget,  while  adding  actions 
to  a  widget  can  make  it  behave  in  ways  the  designer  did  not  foresee  and  that  the  user  might 
not  expect.  Nonetheless,  there  are  cases  in  which  the  best  way  to  implement  the  desired 
behavior  is  to  add  actions  to  an  existing  widget 

In  addition  to  callbacks  and  actions,  it  is  also  possible  for  an  application  (or  a  widget)  to 
implement  event  handlers,  which  use  a  specific  event-selection  mechanism  similar  to  that 
used  in  Xlib.  Event  handlers  are  rarely  used  by  application  programmers,  since  actions  are 
simpler  and  more  configurable. 

Some  widgets  also  declare  public  routines,  which  can  be  used  by  an  application  to  control 
aspects  of  the  widget's  behavior  or  to  get  widget  data.  Usually,  the  purpose  of  public  rou 
tines  is  to  provide  a  more  convenient  means  for  setting  or  getting  widget  data  that  would 
otherwise  have  to  be  accessed  through  resources. 

2.1.6   Xt  and  Object-oriented  Programming  (OOP) 

Xt  provides  an  object-oriented  programming  (OOP)  style,  where  the  objects  are  widgets. 
However,  since  Xt  is  written  in  C,  a  language  that  provides  no  special  support  for  OOP,  Xt 
depends  on  programming  conventions  and  programmer  discipline  to  maintain  the  semblance 
of  objects.  It  is  very  important  that  the  programmer  understand  the  goals  and  rules  of  OOP, 
because  the  language  and  the  system  won't  enforce  these  rules.  If  you  are  familiar  with 
another  object-oriented  system,  you  will  need  to  understand  Xt's  particular  implementation 
of  OOP.  On  the  other  hand,  if  Xt  is  your  first  exposure  to  OOP,  an  explanation  of  its  goals 
and  concepts  should  make  the  whole  system  make  a  lot  more  sense. 

Traditionally,  object-oriented  programming  is  defined  in  terms  of  the  five  words  object, 
method,  message,  class,  and  instance,  and  the  concept  of  encapsulation.  We've  already 
talked  about  classes  and  instances.  This  section  describes  the  remainder  of  these  terms. 

2.1.6.1    The  Object 

In  OOP,  an  object  contains  two  elements:  the  data  that  represents  a  state,  and  code  that  reads 
or  writes  that  data  (called  methods).  For  example,  the  string  displayed  by  a  Label  widget  is 
part  of  its  state  data,  and  the  code  that  actually  draws  the  string  on  the  window  is  a  method 
that  reads  the  state  data.  Inside  widget  code,  the  state  data  is  represented  as  structure  mem 
bers,  and  the  methods  are  represented  as  pointers  to  functions.  Some  state  data  members  are 
public;  they  are  resources  that  can  be  set  or  retrieved  from  outside  the  object.  Other  state 
data  members  are  private;  they  cannot  be  read  or  written  from  outside. 
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2.1.6.2    Methods 


What  is  called  a  method  in  traditional  OOP  is  either  a  method  or  an  action  in  Xt.  In  Xt, 
methods  are  a  set  of  functions  that  are  fixed  for  a  particular  class,  triggered  in  fixed  ways  in 
response  to  Xt  function  calls  made  by  the  application  (with  one  special  case,  the  expose 
method,  triggered  directly  by  the  Expose  event).  A  widget's  methods  supply  its  most  basic 
functions,  such  as  the  code  needed  to  create  a  widget  or  to  change  its  resources.  Actions,  on 
the  other  hand,  are  called  in  response  to  the  events  specified  in  a  translation  table,  and  are 
thus  user  configurable.  Actions  supply  most  of  the  features  of  widgets,  and  these  features  can 
be  added  to  or  replaced  by  the  application,  as  demonstrated  in  Sections  2.4.2, 4.3,  and  4.4. 


2.1.6.3    Messages 


In  pure  OOP,  input  to  objects  and  communication  between  them  are  called  messages.  In  Xt, 
however,  the  forms  of  communication  are  function  calls,  events,  actions,  and  callbacks.  As 
you  have  seen,  applications  can  communicate  with  widgets  using  function  calls,  such  as  to 
set  or  get  widget  resources  using  XtSetValues  and  xtGetValues.  Widgets  also 
respond  directly  to  events  from  the  user.  Widgets  contact  the  application  when  certain  things 
occur  using  callbacks  or  actions.  Widgets  pass  data  back  and  forth  using  special  kinds  of 
events.  All  these  types  of  communication  can  be  thought  of  as  forms  of  messages. 


2.1.6.4    Encapsulation 


Objects  are  intended  to  be  black  boxes  with  documented  inputs  and  outputs.  In  other  words,  a 
program  that  uses  an  object  must  not  depend  on  the  internal  implementation  of  the  object,  but 
instead  only  on  the  known  inputs  and  outputs.  This  is  called  code  encapsulation.  The  advan 
tages  of  code  encapsulation  are  that  programmers  can  use  the  object  without  needing  to 
understand  its  internal  implementation  (hiding  details),  and  that  the  internal  implementation 
of  the  object  can  be  changed  at  any  time  because  no  other  code  depends  on  it.  This  can  be 
stated  in  another  way:  it  minimizes  interdependencies.  In  large  software  projects,  this  one 
feature  makes  OOP  worthwhile. 

This  encapsulation  is  very  effective  in  Xt.  You  should  be  able  to  get  a  long  way  toward  com 
pleting  an  application  without  even  needing  to  know  what  the  code  inside  a  widget  looks 
like,  let  alone  the  details  that  implement  a  particular  widget  For  that  reason,  in  this  book  we 
don't  show  you  what  is  inside  a  widget  until  Chapter  5,  Inside  a  Widget.  Even  when  you  do 
know  how  widgets  are  implemented,,  it  is  a  good  idea  to  "forget"  while  writing  application 
code,  so  that  you  are  not  tempted  to  depend  on  implementation  details. 

Each  widget  class  has  a  public  include  file  and  a  private  include  file.  The  application 
includes  just  the  public  include  file,  while  the  actual  widget  code  includes  the  private  (which 
happens  also  to  include  the  public).  The  names  of  both  include  files  are  based  on  the  class 
name  of  the  widget,  but  the  private  include  file  adds  the  letter  P  to  the  end.  For  example,  the 
Label  widget's  public  include  file  isLabelh,  while  its  private  include  file  isLabelP.h.  Appli 
cation  code  should  include  only  the  public  include  file,  to  maintain  the  desired  encapsulation. 
It  is  tempting  for  beginning  Xt  programmers  to  include  the  private  include  file,  because  it 
allows  you  to  take  shortcuts,  but  you  should  resist  the  temptation.* 


*In  a  language  designed  for  OOP,  such  as  C++,  these  shortcuts  are  generally  prevented  by  the  compiler  or  by  the  lan 
guage  itself. 
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2.2  Structure  of  X  Toolkit  Applications 

All  Toolkit  applications  have  the  same  basic  structure,  as  follows: 

1.  Include  <X11  /Intrinsic. h>  and  <Xll/StringDefs.h>,  the  standard  include  files  for  Xt. 

2.  Include  the  public  include  file  for  each  widget  class  used  in  the  application.  (Each  widget 
class  also  has  a  private  include  file,  which  is  used  in  the  widget  code.) 

3.  Initialize  the  Toolkit  with  the  convenience  function  xtlnitialize.  (Complex  appli 
cations  may  need  to  use  four  separate  calls,  to  xtToolkitlnitialize,  xt- 
CreateApplicationContext,      XtDisplaylnitialize,      and      XtApp- 
CreateShell.) 

4.  Create  widgets  and  tell  their  composite  parent  widget  about  them.  This  requires  one  call 
to  xtCreateManagedWidget  for  each  widget  Separate  xtCreateWidget  and 
xtManageChildren  calls  can  also  be  used  to  speed  startup  of  applications  with  many 
widgets. 

5.  Register  callbacks,  actions,  and  event  handlers,  if  any,  with  Xt. 

6.  Realize  the  widgets  by  calling  xtRealizeWidget.  This  function  has  to  be  called 
only  once  for  the  entire  application,  on  the  shell  widget  returned  by  xtlnitialize. 
This  step  actually  creates  the  windows  for  widgets  and  maps  them  on  the  screen.  This 
step  is  separate  from  creating  the  widgets  themselves,  because  it  allows  all  interdepen 
dent  widgets  to  work  out  their  relative  size  and  position  before  any  windows  are  created. 
(More  on  this  topic,  called  geometry  management,  in  Chapter  11,  Geometry  Manage 
ment.) 

7.  Begin  the  loop  processing  events  by  calling  XtMainLoop.  At  this  point,  Xt  takes  con 
trol  of  your  application  and  operates  the  widgets.  If  any  widgets  are  to  call  functions  in 
your  application,  you  must  have  registered  these  functions  with  Xt  before  calling  xt- 
MainLoop. 

The  four  steps  (3  through  6  above)  of  initializing  the  Toolkit,  creating  widgets,  registering 
application  functions  with  Xt,  and  realizing  widgets,  comprise  the  setup  phase  of  the  applica 
tion.  Your  application  should  do  as  much  of  its  work  as  possible  in  this  phase,  before  calling 
XtMainLoop,  in  order  to  speed  up  the  second  phase  of  the  application,  which  is  the  event 
loop.  This  policy  improves  the  response  time  to  user  events.*  As  we  will  see  in  Chapter  5, 
Inside  a  Widget,  this  policy  also  applies  to  the  code  inside  a  widget  It  is  basic  to  X,  and 
indeed  to  any  event-driven  system. 


*In  X  protocol  terms,  the  setup  phase  consists  of  requests  to  the  server  that  are  generally  long,  and  often  require  im 
mediate  replies,  which  tends  to  slow  performance.  The  event  loop  phase,  on  the  other  hand,  generally  consists  of 
short  requests  and  very  few  "round-trip"  requests.  For  a  full  description  of  this  concept,  see  the  introductory  chapter 
to  Volume  Zero,  X  Protocol  Reference  Manual. 
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2.3  A  Simple  X  Toolkit  Application 

Some  application  code  that  uses  the  X  Toolkit  will  go  a  long  way  to  illustrate  the  basic  con 
cepts  introduced  above. 

Figure  2-11  shows  the  actual  window  created  by  a  minimal  "hello,  world"  Toolkit  application 
xhello,  and  Example  2-1  shows  the  code  for  it  xhello  simply  displays  the  string  "hello"  in  a 
window. 


Figure  2-11.  xhello:  appearance  on  screen 

Some  window  managers  may  add  a  decorated  border  above  or  surrounding  the  window;  it  is 
not  part  of  the  application.  Likewise,  the  placement  of  the  widget  on  the  screen  depends  on 
the  window  manager.  Since  no  coordinates  are  specified  as  resources  for  the  widget,  uwm  or 
twm  will  require  the  user  to  place  it  interactively.  Another  window  manager  might  place  it  at 
some  arbitrary  default  location. 


2.3.1    The  Code 


Example  2-1  shows  the  code  for  xhello. c. 

Example  2-1.  xhello.c:  a  minimal  "helb,  world"  application 


I* 


*  xhello.c  -  simple  program  to  put  up  a  banner  on  the  display 
*/ 

/* 

*  Include  files  required  for  all  Toolkit  programs 

*/ 

tinclude  <Xll/Intrinsic.h>      /*  Intrinsics  Definitions*/ 

tinclude  <Xll/StringDefs.h>     /*  Standard  Name-String  definitions*/ 

/* 

*  Public  include  file  for  widgets  we  actually  use  in  this  file. 

*/ 

#ifdef  X11R3 

/*  Athena  Label  Widget  */ 
/*  R4  or  later  */ 
/*  Athena  Label  Widget  */ 
/*  X11R3  */ 


tinclude  <Xll/Label  .h> 

telse 

tinclude  <Xll/Xaw/Label  .h> 

tendif 

main(argc,  argv) 

int  argc; 

char  **argv; 
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Example  2-1.  xhello.c:  a  minimal  "hello,  world"  application  (continued) 

Widget  topLevel,  hello; 

topLevel  =  Xtlnitialize ( 

argv[0],  /*  Application  name  */ 

"XHello",  /*  Application  class  */ 

NULL,  /*  Resource  Mgr .  options  */ 

0,  /*  number  of  RM  options  */ 

Sargc,  /*  number  of  args  */ 

argv  /*  command  line  */ 
); 

hello  =  XtCreateManagedWidget ( 

"hello",  /*  arbitrary  widget  name  */ 

labelWidgetClass,  /*  widget  class  from  Label. h  */ 

topLevel,  /*  parent  widget*/ 

NULL,  /*  argument  list  */ 

0  /*  arg  list  size  */ 

); 

/* 

*  Create  windows  for  widgets  and  map  them. 
*/ 

XtRealizeWidget (topLevel)  ; 

/* 

*  Loop  for  events. 
*/ 

XtMainLoop ( ) ; 

} 

Each  of  the  four  Xt  Intrinsics  calls  in  xhello  do  more  than  meets  the  eye: 

•  Xtlnitialize  performs  several  important  tasks.  It  reads  the  resource  databases  and 
merges  in  any  arguments  found  on  the  command  line  so  that  Xt  can  use  this  information 
to  configure  widgets  as  they  are  created.  It  also  opens  a  connection  to  the  server,  and  cre 
ates  a  Shell  widget  that  is  designed  to  interact  with  the  window  manager  and  to  be  the 
parent  for  other  widgets  created  in  the  application. 

The  first  and  second  arguments  to  Xtlnitialize  are  the  name  and  class  of  the  appli 
cation.  Originally,  the  idea  was  that  one  might  define  classes  of  applications,  such  as 
"editor,"  of  which  various  text  editors  might  be  considered  instances.  As  it  has  turned 
out,  though,  the  first  argument  is  unused,  and  the  Shell  widget  returned  by  Xt 
lnitialize  obtains  the  application  name  from  argv.  The  second  argument  specifies 
the  name  of  the  application-defaults  file,  in  which  default  resource  settings  are  esta 
blished.  As  mentioned  above,  by  convention,  this  file  has  the  same  name  as  the  applica 
tion,  with  the  first  letter  capitalized,  or  if  the  application  name  begins  with  X,  the  first  two 
letters  capitalized.  For  the  current  application,  we've  specified  the  first  argument  any 
way,  for  compatibility  with  future  releases  which  might  make  use  of  it,  and  have  specified 
the  second  argument  as  XHello. 

The  third  and  fourth  arguments  are  a  pointer  to  and  length  of  an  array  of  application- 
specific  command-line  arguments  (which  we'll  tell  you  how  to  construct  in  Chapter  3, 
More  Widget  Programming  Techniques;  here,  these  arguments  are  unused).  The  fifth  and 
sixth  arguments  are  the  common  argc  and  argv — which  Xtlnitialize  parses  for 
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a  variety  of  standard  X  Toolkit  options  (described  in  Chapter  3,  More  Widget  Program 
ming  Techniques,  and  on  the  Xt Initialize  page  in  Volume  Five,  X  Toolkit  Intrinsic* 
Reference  Manual). 

Xt  Initialize  removes  all  arguments  it  recognizes  from  argc  and  argv,  except  for 
the  application  name.  The  program  can  check  if  more  than  one  argument  remains,  and  if 
so,  abort  with  an  error  message. 

The  Shell  widget  returned  by  the  call  to  Xt  Initialize  is  used  as  the  parent  of  all 
other  widgets  in  the  application  (except  pop  ups,  which  receive  their  own  pop-up  shell 
parent) 

The  xtCreateManagedWidget  call  both  creates  the  Label  widget  and  tells  the  par 
ent  (the  Shell  widget)  that  the  Label  widget's  geometry  is  to  be  managed.  It  is  also  pos 
sible  to  call  XtCreateWidget  and  either  xtManageChild  or  xtManage- 
Children  separately,  but  this  is  usually  done  only  if  you  want  to  create  several  widg 
ets,  and  then  put  them  under  parental  management  all  at  once. 

XtCreateManagedWidget  is  used  for  creating  any  class  of  widget  The  first  argu 
ment  is  the  instance  name,  which  Xt  uses  to  look  up  settings  in  the  resource  database. 
The  second  argument  specifies  the  class  of  widget  to  create — this  variable  comes  from 
the  include  file  for  that  widget,  and  should  always  be  documented  on  the  reference  page 
for  a  widget  The  third  argument  is  the  parent,  which  in  this  case  is  the  widget  returned 
by  xtlnitialize,  but  in  a  more  complex  example  could  be  a  composite  widget 
deeper  in  a  hierarchy  of  nested  widgets.  The  fourth  and  fifth  arguments,  unused  in  this 
example,  are  for  hardcoding  widget  resources.  (More  on  this  in  the  next  section.) 

Notice  that  XtCreateManagedWidget  and  Xtlnitialize  each  return  a  value  of 
type  widget.  This  type  is  an  opaque  pointer  that  is  used  to  refer  to  a  widget  instance.  It 
is  used  anywhere  in  the  application  that  you  need  to  refer  to  a  particular  widget  We 
sometimes  refer  to  this  as  a  widget  ID,  since  even  though  it  is  a  pointer  to  a  structure,  the 
individual  fields  in  that  structure  should  never  be  accessed  from  the  application. 

The  steps  of  initializing  the  Toolkit  and  creating  widgets  seem  logical.  However,  what 
does  it  mean  to  realize  a  widget?  xtRealizeWidget  actually  makes  windows  for  the 
widgets,  whereas  creating  the  widgets  simply  creates  and  initializes  various  internal 
widget  data  structures.*  Creation  and  realization  of  widgets  are  separate  because  some 
window  geometries  cannot  be  known  until  all  the  widgets  are  created  and  the  composite 
widgets  have  determined  their  geometries.  The  realization  step  says  "OK,  all  the  widgets 
are  created  now;  calculate  their  sizes  and  positions  and  make  windows  for  them."  How 
ever,  note  that  it  is  acceptable  to  create  additional  widgets  after  calling  xtRealize 
Widget  as  long  as  there  is  a  good  reason  to  do  so  (such  as  if  it  cannot  be  known  whether 
the  widget  would  be  needed  until  a  certain  user  event  arrives). 

The  realization  step  also  maps  all  the  widget  windows.  Mapping  is  an  X  concept,  not 
something  added  by  Xt.  Mapping  a  window  makes  it  eligible  for  display.  For  a  window 
to  actually  become  visible,  all  its  ancestors  must  be  mapped.  Since 


*A  widget  is  a  client-side  object  It  has  no  presence  on  the  server  other  than  as  a  normal  X  window.  The  Xt  and 
widget  set  libraries  running  on  the  client  side  maintain  the  data  that  allow  programs  to  work  with  the  abstraction  per 
ceived  as  a  widget 
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XtRealizeWidget  is  called  for  the  widget  created  by  Xtlnitialize,  which  is 
the  ancestor  of  all  widgets  in  the  application,  the  end  result  is  that  the  entire  application  is 
displayed.* 

XtMainLoop  transfers  control  of  the  application  to  Xt.  From  this  point  on,  Xt  drives 
all  the  widgets  in  response  to  events,  and  it  interacts  with  the  application  only  at  times  the 
application  has  arranged  ahead  of  time,  xhello  did  not  arrange  any  interaction  with  the 
widget,  so  Xt  operates  the  Label  widget  completely  without  returning  to  xhello' s  code. 
Examples  2-3  through  2-8  will  demonstrate  how  to  make  such  arrangements. 

Xt  programming  is  event-driven.  XtMainLoop  dispatches  events  to  widgets  and  func 
tions  in  the  order  in  which  they  occur.  These  events  can  be  caused  by  user  actions  such 
as  pressing  a  key  or  by  window  system  actions  such  as  displaying  a  new  window.  This  is 
fundamentally  different  from  procedural  programming,  where  the  application  is  in  charge 
and  polls  for  user  input  at  certain  points. 


2.3.2   Compiling  the  Application 

You  can  get  the  code  for  xhello.c  and  all  the  rest  of  the  examples  in  this  book  via  uucp  or 
anonymous///?  from  either  uunet.uu.net  or  expo.lcs.mit.edu,  as  described  in  the  Preface.  The 
code  is  also  on  the  Release  4  distribution  tape  from  MIT  in  the  "contrib"  section.  It  is  a  good 
idea  to  compile  and  run  each  example  as  it  is  presented. 

The  example  programs  come  with  Imakefiles  that  should  make  building  them  easy  if  you 
have  the  X  source.  To  do  this  you  need  the  intake  program  (which  should  be  in  /usr/lib/Xll), 
and  you  need  the  configuration  files  in  TOPImitlconfig,  where  TOP  is  the  root  of  your  X 
sources.  An  Imakefile  is  a  system-independent  makefile  that  is  used  by  imake  to  generate  a 
Makefile.  This  is  necessary  because  it  is  impossible  to  write  a  Makefile  that  will  work  on  any 
system.  You  invoke  imake  using  the  ximake.sh  shell  script  also  provided  in  the  X  sources. 
Complete  instructions  for  compiling  the  examples  using  imake  are  provided  in  a  README 
file  in  the  example  source. 


"There  are  several  other  conditions  that  can  prevent  or  delay  a  window  from  becoming  visible,  described  in  Section 
2.2.5  of  Volume  One,  Xlib  Programming  Manual  (Section  2.2.4  in  the  2nd  edition  of  Volume  One).  These  will  not 
affect  your  Toolkit  application  as  long  as  you  draw  into  windows  at  the  right  time,  using  one  of  the  techniques  de 
scribed  in  Section  4.3  and  Section  6.3. 
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Is  the  X  Toolkit  Too  Complex? 

An  editorial  aside 


Window  systems  may  be  simple  to  use,  but  they  are  very  complex  to  program.  The  first 
thing  that  strikes  the  novice  X  programmer  is  how  complicated  everything  is.  Learning  to 
program  the  X  Window  System,  even  with  the  help  of  the  X  Toolkit,  is  afar  cry  from  learn 
ing  say,  the  C  programming  language,  where  the  very  first  page  of  the  tutorial  presents  a 
complete  running  program.  The  program  itself  is  trivial,  but  this,  the  "hello  world"  pro 
gram,  has  become  a  tacit  benchmark  ofprogrammability.  The  assumption  is  "if  you  can't 
write  'hello  world'  simply,  things  are  badly  designed." 

In  fact,  "hello,  world"  is  a  pathological  example  for  X;  it  is  a  case  where  the  stylized  scaf 
folding  outweighs  the  functional  code.  You've  just  seen  an  X  Toolkit  equivalent  to  "hello 
world,"  and  it  is  nearly  thirty  lines  long.  But  it  is  node-independent,  does  device- 
independent  graphics,  and  can  be  customized  by  the  user  to  control  what  font  to  use,  and 
what  color  to  use  for  the  border,  background,  and  text. 

The  "hello  world"  example  is  indeed  a  good  benchmark  of  language  complexity,  but  it  is 
not  necessarily  a  good  general  benchmark  for  overall  programming  complexity.  It  is  an 
especially  poor  measure  for  a  system  that  encompasses  a  generalized  distributed  software 
environment,  network  communication,  and  device-independent  graphics.  Most  people 
write  complicated  applications,  not  trivial  programs  like  "hello,  world,"  and  it  is  the  ease 
with  which  a  complicated  program  can  be  written  that  is  the  true  test  of  a  language. 

For  example,  consider  the  difference  in  the  number  of  lines  of  code  between  "hello  world" 
and  a  text  editor.  Kernighan  &  Ritchie's  C  Programming  Language,  where  "hello  world" 
was  first  introduced,  doesn' t  present  an  editor.  However,  Kernighan  and  P laugher' s  Soft 
ware  Tools,  an  equally  sacred  reference  from  the  same  era,  presents  a  text  editor  that  con 
tains  well  over  one  thousand  lines.  Furthermore,  the  editor  is  line-oriented,  not  screen- 
oriented.  By  comparison,  because  of  the  modular  design  of  the  Toolkit,  and  the  develop 
ment  of  widgets  as  reusable  user-interface  components,  a  programmer  can  construct  a 
simple  screen  editor  using  the  Athena  Text  widget  in  about  170  lines  of  code.  This  editor  is 
user-configurable,  device-independent,  and  based  on  a  ready-made  component  that  can 
easily  be  incorporated  into  any  program  needing  to  provide  text-editing  capabilities. 

This  is  not  to  invite  absurd  comparisons  of  incommensurate  programming  tools,  but  to 
emphasize  that  the  complexity  ofX  is  the  outgrowth  of  added  functionality ,  not  unneces 
sary  convolutions  of  straightforward  algorithms.  What  really  matters  is  what  features  are 
provided,  how  difficult  is  it  to  write  the  kind  of  application  you  want  to  write,  and  what 
performance  can  be  achieved. 

— Marie  Langley 
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To  compile  any  of  the  examples  on  a  UNIX  system  without  using  imake,  use  the  following 
command  line: 

cc  -o  filename  filename. c  -IXaw  -IXmu  -IXt  -1X11  -DX11R3 

The  order  of  the  libraries  is  important.  Xaw  relies  on  Xmu  (miscellaneous  utilities),  and  both 
rely  on  Xt.  Both  Xmu  and  Xt  in  turn  depend  on  Xlib  (the  -1X11  link  flag  specifies  Xlib). 

Since  XI 1  Release  4  may  be  available  to  some  but  not  all  readers,  the  examples  use  #if  def 
for  various  elements  different  between  Release  3  and  Release  4,  so  that  the  examples  will 
compile  under  either  release.  If  you  are  running  Release  4,  the  -DX11R3  flag  should  not  be 
specified. 

2.3.3   The  Application-defaults  File 

As  mentioned  above,  the  resource  mechanism  allows  widgets  and  applications  to  be  custom 
ized.  Resources  may  be  declared  by  either  a  widget  or  an  application,  and  can  be  set  from 
any  one  of  several  sources,  including  a  user's  resource  file,  the  command  line,  or  an 
application-specific  defaults  file. 

Each  resource  of  a  widget  has  a  default  value  determined  by  the  widget  class  that  declared 
the  resource.  However,  in  many  cases,  the  application  wants  a  different  default  value,  but 
still  wants  the  user  to  be  able  to  change  the  value  of  that  resource. 

The  Label  widget  is  a  case  in  point.  Example  2-1  (xhello)  set  the  default  string  displayed  in 
the  Label  widget,  "hello,"  by  naming  the  widget  hello  in  the  call  to  xtCreate- 
Managedwidget.  It  just  so  happens  that  the  Label  widget  uses  its  widget  name  as  the 
string  to  be  displayed  if  no  other  string  has  been  specified  in  the  resource  database.  However, 
this  trick  doesn't  exist  for  the  other  resources  of  Label  or  of  other  widgets. 

In  general,  the  application  can't  easily  provide  a  default  value  for  resources  by  hardcoding 
them  in  the  application  source  file.  Even  if  it  could,  changing  these  settings  would  require 
recompiling  the  source.  Xt  provides  a  better  way. 

To  provide  defaults,  applications  should  always  create  an  "application-defaults"  resource  file, 
which  on  UNIX  systems  is  usually  stored  in  the  directory  lusrlliblXlllapp-defaults.  For  any 
application,  the  name  of  this  file  should  be  the  same  as  the  classname  argument  to  xt- 
Initialize.  By  convention,  this  string  is  the  same  as  the  name  of  the  application,  with 
the  first  letter  capitalized.  If  the  application  name  begins  with  X,  the  first  two  letters  should 
be  capitalized.  For  xhello  this  is  XHello* 

Example  2-2  shows  the  contents  of  the  application-defaults  file  necessary  to  make  xhello  dis 
play  the  string  "Hello,  World!"  instead  of  the  default  "hello." 


*Note  that  existing  applications  do  not  always  follow  this  latter  convention.  For  example,  the  application -defaults 
file  for  xmh  is  called  Xmh,  not  XMh. 
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Example  2-2.  XHello:  the  application-defaults  file 
*hello. label:    Hello,    World! 

The  name  of  the  widget  instance  whose  string  we  are  setting  is  hello,  and  the  Label 
widget's  resource  that  sets  the  string  is  label.  After  the  colon  is  the  string  we  want  the 
widget  to  display.  The  string  should  not  be  quoted.  White  space  after  the  colon  is  ignored. 

The  application-defaults  file  has  the  same  format  as  all  other  resource  database  files.  In  brief, 
there  are  two  types  of  resources:  application  resources  and  widget  resources.  The  syntax  for 
specifying  application  resources  is  simple: 

application _name .resource _name:  value 

Widget  resources  are  more  complicated,  since  there  may  be  multiple  instances  of  the  same 
widget  in  an  application.  As  a  result,  you  must  specify  the  name  not  only  of  the  widget,  but  a 
pathname  starting  with  the  application  name  and  containing  the  name  of  each  widget  in  the 
widget  hierarchy  leading  to  the  desired  widget.  For  example,  in  the  application  xhello,  the 
complete  resource  specification  for  the  resource  called  label  for  the  Label  widget  called  hello 
would  be: 

xhello. hello. label:   Hello,  World! 

To  simplify  resource  specifications,  a  wildcard  syntax  may  be  used,  specifying  an  asterisk 
instead  of  a  dot,  and  omitting  one  or  more  terms  of  the  fully  qualified  name.  For  example,  as 
we've  shown  above: 

*hello. label:   Hello,  World! 

or  since  there  is  no  other  Label  widget  in  the  application,  perhaps  even: 

*label:      Hello,    World! 

One  possible  source  of  confusion  is  that  the  shell  widget  instance  returned  by  xt- 
Initialize  should  not  be  named  in  resource  specifications;  part  of  the  behavior  of  this 
widget  class  is  that  it  makes  its  resource  name  the  same  as  the  name  of  the  application  (speci 
fied  on  the  command  line).  If  you  were  to  include  the  widget  name: 

xhello. topLevel. hello. label:   Hello,  World! 

your  resource  specification  would  be  ignored.  Note  that  the  Resource  Manager  provides  no 
error  messages,  and  silently  ignores  resource  specification  errors  (including  syntax  errors),  so 
they  can  be  difficult  to  track  down. 

You  should  also  be  aware  that  resources,  like  widgets,  have  both  instances  (usually  referred 
to  simply  as  their  "names")  and  classes.  Class  names  are  often  the  same  as  the  corresponding 
resource  name,  but  with  the  first  letter  of  the  resource  name  capitalized.  For  example,  the 
color  resource  foreground  has  the  class  Foreground.  In  addition,  there  may  be  other 
resources  (such  as  the  cursor  color,  border  color,  and  so  on)  that  may  also  have  the  class 
Foreground. 

A  resource  class  name  applies  to  all  instances  of  the  resource.  For  example,  all  resources  of 
class  Foreground,  regardless  of  where  in  the  application  or  widget  they  were  found,  could 
be  set  by  specifying: 

*Foreground:   blue 
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Or  the  foreground  resource  in  all  widgets  of  the  Command  widget  class  could  be  set  by  using 
the  widget  class  name  in  place  of  the  instance  name: 

*Command. foreground:   blue 

Because  resource  "instance"  names  take  precedence  over  class  names,  however,  the  devel 
oper  could  override  the  class  setting  with  a  specific  setting  for  an  individual  widget  resource. 

Note  that  all  resource  specifications  are  given  as  strings,  even  though  the  data  required  for 
the  resource  may  be  of  a  different  type.  Xt  automatically  converts  the  string  found  in  the 
resource  database  files  into  the  appropriate  destination  type.  For  example,  colors  are  speci 
fied  as  color  names,  which  are  automatically  converted  to  pixel  values  used  to  look  up  the 
closest  color  available  in  the  colormap  for  the  window.  You  can  also  write  and  add  converter 
routines  for  your  own  special  types.  (For  example,  you  might  define  a  "menu"  data  type,  so 
the  user  could  specify  the  contents  of  a  menu  via  a  resource  setting.)  Note  also  that  while  in 
resource  files,  users  specify  the  resource  name  or  class  as  shown  above;  in  any  Xt  calls  from 
source  code,  you  always  use  symbolic  constants  of  the  form1  xttJresourceName  or  xtCclass- 
Name  (e.g.,  XtNf  oreground  or  XtCForeground).  We'll  explain  the  reason  for  that 
shortly. 

The  complete  list  of  sources  for  resource  database  settings,  the  precedence  rules  the  resource 
manager  uses  for  establishing  the  actual  resource  value  when  there  are  conflicting  settings  in 
different  database  sources,  and  the  mechanics  of  type  conversion,  are  described  in  detail  in 
Chapter  9,  Resource  Management  and  Type  Conversion.  (See  also  Chapter  9  in  Volume 
Three,  X  Window  System  User's  Guide.)  We'll  also  be  returning  to  the  topic  of  resources 
with  each  new  example. 


2.3.4   To  Hardcode  or  Not  to  Hardcode 

There  are  pros  and  cons  to  applications  that  can  be  radically  customized  by  the  user  through 
resources.  The  pros  are  quite  clear:  a  flexible  application  will  meet  the  needs  of  a  wider 
audience.  Some  of  the  cons  are  that  a  user  may  make  a  mistake  in  the  configuration  that 
makes  the  application  inoperable  in  some  way.  Documentation  and  technical  support 
become  much  more  difficult.  A  partial  solution  is  to  document  the  default  resource  specifica 
tions  and  require  that  users  reinstall  those  default  specifications  before  a  technical  support 
person  tries  to  solve  their  problems.  In  some  cases,  dialog  boxes  can  be  added  that  require 
the  user  to  confirm  any  irreversible  actions. 

In  any  case,  you  may  eventually  want  to  hardcode  certain  resources  in  the  application  so  that 
they  are  not  user  configurable.  This  would  be  done  for  resources  that,  if  set  incorrectly, 
would  make  your  application  operate  in  an  unsafe  fashion.  Hardcoding  a  resource  is  done  by 
creating  an  ArgList  structure  and  using  it  as  an  argument  to  the  call  that  creates  a  widget. 
(This  is  the  function  of  the  two  arguments  of  xtCreateManagedwidget  mentioned  in 
Section  2.3.1  as  unused  in  xnello.c.) 

This  technique  is  demonstrated  later,  because  you  won't  need  it  until  the  final  stages  of 
releasing  your  application.  While  an  application  is  under  development,  it  is  better  to  leave 
all  resources  configurable,  because  this  allows  you  to  change  them  in  the  application-defaults 
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file  without  recompiling  the  source.  When  the  code  is  stable  and  almost  ready  for  release, 
then  it's  time  to  determine  which  resources  need  to  be  hardcoded. 


2.4  Connecting  Widgets  to  Application  Code 

The  Toolkit  is  designed  so  that  the  code  that  implements  the  user  interface  and  the  code  that 
implements  application  features  can  be  kept  separate.  This  is  an  advantage,  because  it  allows 
either  part  to  be  modified  without  affecting  the  other.  However,  these  two  pieces  of  code 
need  to  be  intimately  connected,  because  the  user  interface  must  drive  the  application  code. 

This  section  describes  the  two  basic  ways  of  making  this  connection,  using  callbacks  and 
actions.  As  mentioned  earlier,  the  general  idea  of  both  methods  is  that  the  application  regis 
ters  functions  to  be  called  in  sequence  in  response  to  occurrences  within  certain  widgets. 

The  two  techniques  differ  in  the  way  that  the  registered  function  is  invoked.  For  callbacks, 
the  trigger  is  an  abstract  occurrence  defined  by  the  widget,  which  may  or  may  not  be  event 
related.  The  routines  on  a  widget's  callback  list(s)  are  invoked  by  the  widget  code,  using  a 
call  to  xtCallCallbacks.  Actions,  on  the  other  hand,  are  invoked  directly  by  Xt,  as  the 
result  of  an  event  combination  specified  by  the  translations  mechanism. 

The  two  mechanisms  also  differ  in  the  way  they  are  added  to  a  widget.  The  application  can 
add  a  callback  routine  to  a  widget  using  xtAddCallback  or  xtAddCallbacks  only  if 
the  widget  has  declared  a  callback  list  as  a  resource.  Actions,  on  the  other  hand,  can  be 
added  to  a  widget  using  xtAddActions  without  the  widget's  knowledge  or  consent. 

Despite  their  differences,  it  is  easy  for  a  beginner  to  confuse  the  use  of  the  two  mechanisms, 
especially  since  callbacks  are  often  invoked  by  widgets  from  within  action  routines.  For 
example,  the  Command  widget  defines  a  callback  resource  called  xtNcallback  and  sev 
eral  action  routines,  one  of  which  (notify)  simply  calls  the  function  pointed  to  by  the  Xt 
Ncallback  resource. 

When  callbacks  are  called  from  within  predefined  widget  actions,  the  most  obvious  benefit  of 
actions,  namely  access  to  the  high-level  syntax  of  the  Translation  Manager,  also  accrues  to 
callbacks.  This  overlap  in  the  use  of  these  two  mechanisms  can  obscure  the  fundamental  dif 
ference  in  their  purpose. 

Callbacks  allow  widgets  to  provide  hooks  for  applications  to  add  specific  functions.  Call 
backs  should  be  used  when  the  widget  class  has  a  callback  resource  for  the  particular  occur 
rence  that  you  want  to  trigger  your  function.  For  example,  the  Athena  Scroll  widget  defines  a 
scrollProc  callback  to  be  invoked  when  the  pointer  is  clicked  in  the  scrollbar,  and  a 
thumbProc  callback  to  be  invoked  when  the  user  drags  the  thumb  with  the  pointer. 

Actions  have  many  uses  in  the  design  of  widgets,  but  for  applications,  their  main  purpose  is 
to  add  behavior  that  a  widget  does  not  already  provide.  As  noted  earlier,  though,  when  work 
ing  with  a  widget  set  such  as  Motif  or  OPEN  LOOK  that  has  clearly-defined  user-interface 
conventions,  adding  new  behavior  to  a  widget  may  not  be  an  appropriate  thing  to  do.  In 
addition,  using  actions  is  somewhat  more  complex  than  using  callbacks,  and  actions  have  no 
advantages  over  callbacks  when  an  appropriate  callback  is  available. 
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2.4.1    Callbacks 


To  illustrate  the  use  of  callbacks  from  the  application,  we  will  write  an  application  that  uses 
the  Athena  Command  widget  This  type  of  widget  is  also  known  as  a  pushbutton;  some 
analogue  will  be  present  in  every  widget  set.  It  contains  a  string  or  picture,  and  executes  a 
command  when  a  pointer  button  is  clicked  on  it 

A  Command  widget  calls  an  application  function  when  you  press  and  release  the  first  pointer 
button  (by  default)  in  its  window.  It  also  highlights  the  window  border  of  the  Command 
widget  when  you  move  the  pointer  into  it  When  you  press  and  hold  the  pointer  button  in  the 
Command  widget's  window,  the  Command  widget  redraws  the  window  in  reverse  video. 
Moving  the  held  button  out  of  the  window  resets  the  widget  without  executing  the  command. 

The  xgoodbye  program  creates  a  single  Command  widget  It  is  very  similar  to  xhello,  but 
takes  advantage  of  the  callback  provided  by  the  Command  widget  Clicking  on  the  "Good 
bye,  Cruel  World"  button  exits  the  program. 

Figure  2-12  shows  the  window  that  xgoodbye  creates  if  you  have  installed  the  suggested 
application-defaults  file  (otherwise,  it  will  display  "goodbye").  It  is  suggested  that  you  com 
pile  and  run  xgoodbye. c,  testing  its  response  to  moving  the  pointer  in  and  out  of  its  window, 
and  clicking  the  various  pointer  buttons  on  its  window. 


I Goodbye,  Cruel  World!) 


Figure  2-12.  The  appearance  of  xgoodbye  when  the  pointer  is  in  the  window 

This  example  is  not  as  frivolous  as  it  seems.  Many  applications  use  code  identical  to  this  to 
implement  their  "Quit"  button. 

The  code  forxgoodbye.c  is  shown  in  Example  2-3. 

Example  2-3.  xgoodbye.c:  complete  code 

/* 

*  xgoodbye.c  -  simple  program  to  put  up  a  banner  on  the  display 

*  and  callback  an  application  function. 
*/ 

finclude  <stdio.h> 
/* 

*  Include  files  required  for  all  Toolkit  programs 
*/ 

finclude  <Xll/Intrinsic .h>  /*  Intrinsics  Definitions  */ 

#include  <Xll/StringDef s .h> /*  Standard  Name-String  definitions  */ 

/* 

*  Public  include  file  for  widgets  we  actually  use  in  this  file. 
*/ 

lifdef  X11R3 
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Example  2-3.  xgoodbye.c:  complete  code  (continued) 


/*  Athena  Command  Widget  */ 

/*  R4  or  later  */ 

/*  Athena  Command  Widget  */ 

/*  X11R3  */ 


#include  <X11 /Command. h> 

telse 

tinclude  <Xll/Xaw/Command.h> 

#endif 

/* 

*  Quit  button  callback  function 

*/ 

/*  ARGSUSED  */ 

void  Quit (w,  client_data,  call_data) 
Widget  w; 
caddr_t  client_data,  call_data; 

fprintf (stderr,  "It  was  nice  knowing  you.Xn"); 
exit (0)  ; 


main(argc,  argv) 
int  argc; 
char  **argv; 
{ 

Widget  topLevel,  goodbye; 

topLevel  =  Xtlnitialize  ( 
argv[0] , 
"XGoodbye", 
NULL, 
0, 

Sargc, 
argv 


/*  Application  name  */ 

/*  Application  class  */ 

/*  Resource  Mgr .  options  */ 

/*  number  of  RM  options  */ 

/*  number  of  args  */ 

/*  command  line  */ 


goodbye  =  XtCreateManagedWidget ( 

"goodbye",  /*  arbitrary  widget  name  */ 

commandWidgetClass,      /*  widget  class  from  Command. h  */ 
topLevel, 
NULL, 


parent  widget*/ 
argument  list  */ 
arg  list  size  */ 


XtAddCallback (goodbye,  XtNcallback,  Quit,  0) ; 

/* 

*  Create  windows  for  widgets  and  map  them. 

*/ 

XtRealizeWidget (topLevel)  ; 

/* 

*  Loop  for  events. 

*/ 
XtMainLoopO  ; 

} 

And  here  isxgoodbye's  application-defaults  file: 
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Example  2-4.  XGoodbye:  the  application-defaults  file 
*goodbye . label :          Goodbye,    Cruel   World! 

The  differences  between  xgoodbye  and  xhello  all  apply  to  adding  a  callback  function.  In  this 
example  we  have  some  application  code  (the  Quit  function)  that  we  register  with  Xt  as  a 
callback  function  for  the  widget  called  goodbye  using  the  xtAddCallback  call. 

The  Quit  function  is  defined  before  main,  so  that  we  can  use  the  function  pointer  Quit  in 
the  XtAddCallback  call.  It  is  also  possible  to  declare  Quit  as  a  function  pointer  early  in 
the  application,  but  actually  to  define  it  further  down  in  the  source  code. 

The  XtAddCallback  call  used  to  register  Quit  as  the  Command  widget's  callback  is  as 
follows: 

XtAddCallback (goodbye,    XtNcallback,    Quit,    0)  ; 

The  first  argument,  goodbye,  is  the  widget  that  is  to  trigger  the  callback.  The  second  argu 
ment,  XtNcallback,  is  a  symbolic  constant  that  identifies  which  of  the  widget's  callback 
resources  is  being  set  (This  constant,  like  most  resource  names  defined  by  Xt,  is  defined  in 
the  file  <XlllStringDefs.h>.  Additional  resource  names  are  often  defined  by  an  individual 
widget's  public  include  file.)  In  this  particular  case,  the  name  XtNcallback  does  not  shed 
any  light  on  the  real  purpose  of  the  callback.  A  better  name  would  have  been  xtNnot  if  y- 
Callback  or  XtNcommandCallback.  All  widgets  also  have  the  callback  xt- 
NdestroyCallback,  which  is  called  when  the  widget  is  destroyed.  Scroll  widgets  often 
have  at  least  two  callbacks  in  addition  to  xtNdestroyCallback;  in  the  Athena  set  these 
are  called  xtNscrollProc  and  xtNthumbProc,  and  they  are  called,  respectively, 
when  the  user  clicks  in  the  scroll  area  or  drags  the  thumb. 

The  third  argument  of  XtAddCallback  is  the  function  the  widget  is  to  call,  and  the  last 
argument  is  any  data  to  be  passed  to  the  callback  function.  No  data  is  to  be  passed  to  Quit. 

The  Quit  function  itself,  like  all  callback  functions,  takes  three  arguments: 
void   Quit(w,    client_data,    call_data) 

•  The  first  argument  is  the  widget  that  triggered  the  callback,  as  specified  as  the  first  argu 
ment  in  XtAddCallback.  You  would  use  the  value  of  this  argument  in  your  callback 
function  if  you  registered  the  same  function  as  a  callback  for  two  different  widgets,  and  if 
you  wanted  to  distinguish  in  the  callback  which  widget  called  it 

•  The  second  argument,  client_data,  is  the  value  passed  as  the  last  argument  of  Xt 
AddCallback.  This  can  be  any  data  that  you  need  in  the  callback  function. 

•  The  third  argument,  call_data,  is  a  piece  of  data  passed  from  the  widget.   Some 
classes  of  widget  set  this  argument,  but  others  do  not  The  documentation  for  the  widget 
will  specify  the  contents  of  this  data  if  it  is  used.  The  Command  widget  doesn't  provide 
any  call_data,  but  the  Scroll  widget,  for  example,  passes  back  the  current  position  of 
the  thumb. 

If  you  are  intentionally  not  going  to  use  one  or  more  of  these  arguments,  you  should  place  the 
comment  /*ARGSUSED*/  on  the  line  before  the  function.  This  prevents  the  C  program 
checker  lint  from  complaining  about  the  unused  arguments.  See  the  Nutshell  Handbook 
Checking  C  Programs  with  lint  for  more  details.  By  convention,  callback  function  names 
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(and  as  you  will  see,  action  function  names  as  well)  are  capitalized.  This  lessens  the  chance 
of  collision  with  other  variables  names  because  callback  functions  are  global  in  the  source 
file.  The  most  common  collision  is  between  callback  functions  and  widget  IDs  of  type 
widget.  It  is  tempting  to  call  the  quit  callback  function  quit,  and  also  to  call  the  quit 
widget  quit,  but  this  will  result  in  mysterious  errors  or  a  core  dump.  If  you  follow  the  con 
vention  that  callback  functions  are  given  a  capitalized  name,  such  as  Quit,  you  avoid  this 
problem. 


2.4.2    Actions 


The  second  way  of  connecting  an  application  with  a  widget  is  using  actions.  Actions  are 
most  appropriate  for  adding  minor  features  to  an  existing  widget  when  the  widget  does  not 
provide  a  callback  that  you  want,  or  for  building  an  application  window  by  adding  features  to 
a  Core  widget.* 

A  simple  example  that  shows  the  power  of  actions  is  to  replace  the  Quit  callback  function 
shown  in  Example  2-2  with  two  separate  quit  actions,  one  of  which  prompts  the  user  for  con 
firmation,  the  other  of  which  does  not  As  separate  actions,  these  functions  can  be  configured 
to  respond  to  different  events.  Ideally,  we'd  like  to  emulate  the  Macintosh  user-interface 
semantic,  which  allows  a  single  click  to  select  a  button,  which  is  then  confirmed  by  a  carriage 
return  in  response  to  a  dialog  box,  while  a  double  click  performs  the  button's  action  right 
away,  without  confirmation.  However,  the  way  the  Translation  Manager  interprets  event 
sequences,  you  cannot  specify  both  a  single  and  double  click  for  the  same  widget  if  you  want 
them  to  execute  mutually  exclusive  functions  (i.e.,  unless  you  don't  mind  the  single-click 
action  being  executed  in  addition  to  the  double-click  action  whenever  you  double  click). 

Instead,  we'll  have  the  confirm  action  respond  to  a  click  of  the  first  pointer  button,  and  quit 
without  confirmation  in  response  to  the  second. 

Here's  the  complete  code  for  xfarewell.c. 

Example  2-5.  xfarewell.c:  complete  code 

/* 

*  xfarewell.c  -  simple  program  to  provide  a  Command  widget  that 

*  performs  a  different  action  in  response  to  a 

*  click  of  the  first  and  second  pointer  buttons. 
*/ 

tinclude  <stdio.h> 


*  Usually,  when  a  widget  does  not  provide  a  certain  callback,  it  also  does  not  provide  various  other  characteristics  that 
you  want  For  example,  to  make  the  Label  widget  work  like  Command  (assuming  the  Command  widget  didn't  al 
ready  exist),  you  would  have  to  make  it  accept  more  kinds  of  input,  add  the  drawing  code  to  highlight  the  border  and 
draw  the  text  in  reverse  video,  and  add  the  ability  to  call  an  application  function.  All  this  can  be  done  with  actions, 
but  it  would  take  a  lot  of  work.  What  makes  it  difficult  is  that  your  code  may  interact  with  the  widget's  code  in  un 
pleasant  ways.  When  the  changes  are  so  major,  it  makes  more  sense  to  create  a  new  widget  subclass,  which  shares 
some  characteristics  and  code  with  its  superclass.  As  we  will  see,  that  is  exactly  how  Command  is  implemented,  as  a 
subclass  of  Label.  The  Core  widget,  on  the  other  hand,  has  no  input  or  output  semantics  at  all,  and  therefore  is 
simpler  to  add  actions  to  without  conflict  We'll  demonstrate  a  simple  feature  addition  here,  and  demonstrate  the  use 
of  the  Core  widget  in  Chapter  4,  An  Example  Application. 
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Example  2-5.  xfarewell.c:  complete  code  (continued) 

/* 

*  Include  files  required  for  all  Toolkit  programs 
*/ 

#include  <Xll/Intrinsic .h>       /*  Intrinsics  Definitions  */ 

tinclude  <Xll/StringDef s .h>      /*  Standard  Name-String  definitions  */ 

/* 

*  Public  include  file  for  widgets  we  actually  use  in  this  file. 
*/ 

tifdef  X11R3 

finclude  <X1 I/Command. h>         /*  Athena  Command  Widget  */ 

#else  /*  R4  or  later  */ 

#include  <Xll/Xaw/Command.h>     /*  Athena  Command  Widget  */ 

#endif  /*  X11R3  */ 

/* 

*  Confirm  action 
V 

/*ARGSUSED*/ 

static  void  Confirm (w,  event) 

Widget  w; 

XButtonEvent  *event; 

/*    following  action  args  not  used: 

*  String  *params; 

*  Cardinal  *num_params; 
*/ 

{ 
/* 

*  Once  we  show  how  to  do  it,  we  could  pop  up  a  dialog  box  to  do  this. 

*  Since  we  haven't  yet,  simply  print  a  message  to  stderr. 
*/ 

fprintf (stderr,  "Are  you  sure  you  want  to  exit?\n\ 

Click  with  the  middle  pointer  button  if  you're  sure.Xn") 
} 

/* 

*  Quit  action 
*/ 

/*ARGSUSED*/ 

static  void  Quit (w,  event,  params,  num_params) 

Widget  w; 

XButtonEvent  *event; 

String  *params;  /*  unused  */ 

Cardinal  *num_params;  /*  unused  */ 

{ 

fprintf (stderr,  "It  was  nice  knowing  you.\n"); 

exit (0) ; 
} 

main  (argc,  argv) 
int  argc; 
char  **argv; 
{ 

Widget  topLevel,  farewell; 

static  XtActionsRec  two_quits [ ]  =  { 
{"confirm",  Confirm}, 
{"quit",  Quit}, 
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Example  2-5.  xfarewell.c:  complete  code  (continued) 


}; 

topLevel    =   Xtlnitialize ( 

argv[0],  / 

"XFarewell",  / 

NULL,  /•• 

0,  /' 

&argc,  /• 

argv  /: 


Application  name  */ 
Application  class  */ 
Resource  Mgr .  options 
number  of  RM  options 
number  of  args  */ 
command  line  */ 


farewell  =  XtCreateManagedWidget ( 


} 


"farewell", 

commandWidget Class, 

topLevel, 

NULL, 

0 


/*  arbitrary  widget  name  */ 

/*  widget  class  from  Command. h  */ 

/*  parent  widget*/ 

/*  argument  list  */ 

/*  arg  list  size  */ 


XtAddActions (two_quits,  XtNumber (two_guits) ) 

/* 

*  Create  windows  for  widgets  and  map  them. 
*/ 

XtRealizeWidget (topLevel)  ; 

/* 

*  Loop  for  events. 
*/ 

XtMainLoop ( ) ; 


In  Example  2-3  above,  we  have  dispensed  entirely  with  the  use  of  the  Command  widget's 
callback.  Instead,  we  have  implemented  two  separate  application  functions,  Confirm  and 
Quit,  that  will  be  registered  as  actions  of  the  Command  widget.  To  make  the  actions  avail 
able,  you  must  declare  an  actions  table,  which  maps  function  pointers  to  strings  that  the  user 
can  reference  in  a  translation  table. 

You  must  register  the  actions  table  with  Xt  by  calling  XtAddActions.  (The  XtNumber 
call  counts  the  number  of  entries  defined  in  the  actions  table — you  will  see  this  macro  often.) 
You  should  also  create  a  default  translation  table  and  store  it  in  the  application-defaults  file. 

2.4.2.1    The  Actions  Table 

The  format  of  an  Actions  Table  is  defined  as  follows: 

typedef  struct  _XtActionsRec { 

char  *string; 

XtActionProc  proc; 
}  XtActionsRec; 

By  convention,  the  string  and  the  function  name  are  identical,  except  that  the  function  name 
should  begin  with  an  upper-case  letter,  as  in  the  following  example: 
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static  XtActionsRec  two_quits [ ]  =  { 

{"confirm",  Confirm}, 

{"quit".  Quit}, 
}; 

This  mapping  from  strings  to  function  pointers  is  necessary  to  allow  translation  tables  to  be 
specified  in  resource  files,  which  are  made  up  entirely  of  strings. 

2.4.2.2    Format  of  an  Action  Procedure 

An  xt  Action?  roc  is  just  a  function  with  four  arguments:  a  widget,  an  event,  a  string  con 
taining  any  arguments  specified  for  the  action,  and  the  number  of  arguments  contained  in  the 
string.  The  purpose  of  the  last  two  arguments  will  be  described  later.  When  you  don't  pass 
any  arguments,  you  can  call  your  action  function  with  only  the  first  two  arguments,  as  shown 
in  Example  2-6. 

Example  2-6.  An  XtActionProc  with  widget  and  event  arguments 

/*ARGSUSED*/ 

static  void  Confirm (w,  event) 

Widget  w; 

XButtonEvent  *event; 

{ 

/* 

*  Once  we  show  how  to  do  it,  we  can  pop  up  a  dialog  box  to  do 

*  this.   Since  we  haven't  yet,  simply  print  a  message  to  stderr. 

II    */ 

fprintf (stderr,  "Are  you  sure  you  want  to  exit?\n\ 

Click  with  the  middle  pointer  button  if  you're  sure.\n"); 
} 

If  the  additional  arguments  are  declared,  but  not  used,  you  should  be  sure  to  include  the  lint 
comment  /*ARGSUSED*/. 

One  major  difference  between  an  action  function  and  a  callback  function  is  that  action  func 
tions  are  called  with  an  event  as  an  argument,  while  actions  do  not  have  the  client_data 
or  call_data  arguments  present  for  callback  functions.  This  means  the  only  way  to  pass 
application  data  into  an  action  function  is  through  global  variables.  The  presence  of  the 
event  argument  means  that  you  can  use  the  contents  of  the  event  structure  in  the  action  func 
tion.  However,  be  aware  that  if  you  are  allowing  user  configuration  of  the  translation  table, 
an  action  may  be  called  with  different  kinds  of  events.  You  should  at  least  check  the  event 
type  in  the  action  routine  and  print  an  appropriate  message  if  the  user  has  arranged  to  call  the 
action  with  the  wrong  type  of  event  We'll  show  how  to  do  this  in  Chapter  7,  Events,  Trans 
lations,  and  Accelerators. 
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2.4.2.3    The  Translation  Table 

Actions  are  global  to  an  application.  But  even  so,  a  widget  uses  actions  only  when  config 
ured  to  do  so,  using  a  translation  table  resource,  XtNtranslations. 

Every  widget  that  has  actions  also  has  a  translation  table  that  maps  event  combinations  into 
those  actions.  The  application  can  override,  augment,  or  replace  this  table  to  make  a  widget 
call  application-registered  actions  instead  of  or  in  addition  to  the  widget's  own  actions.  Reg 
istering  actions  with  xtAddActions  makes  them  eligible  for  inclusion  in  translation 
tables. 

Each  line  of  a  translation  table  maps  a  sequence  of  events  to  a  sequence  of  actions.  The 
entire  translation  table  is  simply  a  string  consisting  of  one  or  more  event  specifications  in 
angle-brackets,  with  optional  modifiers,  followed  by  a  colon  and  a  function  name  string 
defined  in  an  action  table.  Multiple  translations  are  specified  as  part  of  the  same  string.  By 
convention,  the  string  is  continued  on  several  lines,  one  for  each  translation,  with  each  line 
except  the  last  terminated  with  a  linefeed  (\n)  and  a  backslash  (\). 

We'll  describe  the  details  of  event  specification  and  other  aspects  of  translation  table  syntax 
in  Chapter  7,  Events,  Translations,  and  Accelerators.  For  now,  an  example  should  get  the 
point  across  quite  clearly. 

The  default  translations  for  the  Command  widget  are  as  follows: 

<EnterWindow>:  highlight ()  \n\ 

<LeaveWindow> :  reset  ()  \n\ 

<BtnlDown>:  set()  \n\ 

<BtnlUp>:  notify ()  unset () 

That  is  to  say,  when  the  pointer  enters  the  widget,  the  widget's  highlight  action  will  be 
called  (this  function  darkens  the  border  of  the  widget);  when  the  pointer  leaves  the  window, 
the  widget  will  be  reset  to  its  original  state.  On  button  1  (the  left-most  pointer  button) 
being  pressed,  the  widget's  set  action  displays  it  in  reverse  video;  on  button  up,  the 
widget's  notify  action  (which  simply  calls  the  application  function  pointed  to  by  the  xt- 
Ncallback  resource)  will  be  activated,  and  the  unset  action  will  return  the  widget  to  its 
normal  appearance.  Note  that  unset  ()  and  notify  ()  are  both  called  on  the  last  line: 
more  than  one  action  can  be  called  in  response  to  a  single  event  or  event  combination. 

Example  2-7  shows  the  application-defaults  file  for  xfarewell,  which  modifies  this  default 
translation  table. 

Example  2-7.  XFarewell:  the  application-defaults  file 

*farewell . label :   Click  on  me. 
*farewell .translations :  #override\n\ 

<BtnlDown>, <BtnlUp> :      confirm ( ) \n\ 

<Btn2Down>:  set()\n\ 

<Btn2Down>,<Btn2Up>:      quit() 

The  resource  set  here  is  translations.  (This  resource  has  the  same  name  for  all  widg 
ets.)  The  string-to-translation-table  resource  converter  recognizes  one  of  three  directives, 
beginning  with  #  on  the  first  line,  which  tells  how  to  handle  existing  translations  (either  set  as 
widget  defaults,  or  in  other  resource  database  files): 
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•  # replace  (the  default  if  no  directive  is  specified)  says  simply  to  replace  the  old  trans 
lations  with  the  current  table. 

•  # augment  says  to  merge  the  new  translations  into  the  existing  translation  table,  but  not 
to  disturb  any  existing  translations.  If  a  translation  already  exists  for  a  particular  event, 
the  conflicting  translation  specification  in  a  table  beginning  with  #augment  is  ignored. 

•  #  over  ride  says  to  merge  the  new  translations  into  the  existing  translation  table, 
replacing  old  values  with  the  current  specifications  in  the  event  of  conflict. 

We  used  ^override  because  this  allows  us  to  keep  the  translations  for  <EnterWindow> 
and  <LeaveWindow>  events  in  place.  In  addition,  the  Command  widget's  set  and 
unset  actions  will  also  remain  in  effect  for  <BtnlDown>  and  <BtnlUp>.  (For  more 
details  on  why  these  aren't  overridden  by  the  new  translations,  see  Chapter  7,  Events,  Trans 
lations,  and  Accelerators.) 

The  translation: 

<BtnlDown>,<BtnlUp>:       confirm () 

specifies  that  the  confirm  action  should  be  called  in  response  to  a  pair  of  events,  namely  a 
button  press  followed  by  a  button  release,  with  no  other  events  intervening. 

The  translations: 

<Btn2Down> :  set ( ) \n\ 

<Btn2Down>,<Btn2Up>:     quit{) 

specify  that  the  Command  widget's  internal  set  action  should  be  invoked  by  pressing  but 
ton  2,  and  that  our  own  quit  action  should  be  invoked  by  clicking  button  2.  Note  that  we 
don't  bother  to  bind  the  Command  widget's  unset  action  to  <Btn2Up>,  since  the 
application  will  disappear  as  a  result  of  the  quit  action.  (The  unset  action  is  still  used 
when  the  user  presses  button  2  and  then  moves  the  pointer  outside  the  widget  before  releas 
ing  button  2.  This  is  one  of  Command's  default  bindings  that  we  have  not  overridden.)  If  we 
were  using  the  widget  for  any  other  purpose,  we  would  map  <Btn2Up>  to  unset,  so  that 
the  widget  was  restored  to  its  normal  appearance  when  our  own  action  was  completed. 

2.4.2.4    Hardcodlng  Translations 

There  are  cases  in  which  an  application  may  want  not  only  to  specify  translations  in  an 
application-defaults  file,  but  also  to  hardcode  them  into  the  application.  When  you  specify 
translations  only  in  the  application-defaults  file,  the  user  has  unlimited  configurability;  if  the 
default  translations  are  deleted  or  changed  beyond  recognition,  the  application  may  no  longer 
work. 

Three  Xt  functions  are  used  for  setting  translation  tables  from  the  application  code: 

•  xtParseTranslationTable  is  used  to  compile  a  string  translation  table  into  the 
opaque   internal   representation   XtTranslations.    (For  translations   specified  in 
resource  files,  this  conversion  is  performed  automatically  by  a  resource  converter.) 

•  Xt  Augment  Translations  is  used,  like  the  #augment  directive  in  a  resource  file, 
to  nondestructively  merge  translations  into  a  widget's  existing  translations. 
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•     XtOverrideTranslations  is  used,  like  the  #override  directive  in  a  resource 
file,  to  destructively  merge  translations  into  a  widget's  existing  translations. 

Both  XtAugmentTranslations  and  XtOverrideTranslations  take  as  argu 
ments  a  widget  and  a  compiled  translation  table  returned  by  xtParseTranslation- 
Table. 

There  is  no  function  to  completely  replace  a  widget's  translations;  however,  you  can  do  this 
by  calling  xt  Set  Values,  the  general  routine  for  setting  resources  (whose  use  is  demon 
strated  later  in  this  chapter)  to  set  the  value  of  a  widget's  xtNtranslations  resource  to 
a  compiled  translation  table  returned  by  xtParseTranslationTable. 

To  set  the  same  translations  specified  in  the  application-defaults  file  from  the  application 
itself,  we  would  have  used  the  following  code: 

Example  2-8.  Code  Fragment:  specifying  translations  in  the  program 

static  char  defaultTranslations [ ]  =  "#override\n\ 
<BtnlDown>, <BtnlUp> :     confirm ( ) \n\ 
<Btn2Down>:  set()\n\ 

<Btn2Down>,<Btn2Up>:     quit()n; 

XtTranslations  mytranslations; 


mytranslations  =  XtParseTranslationTable (defaultTranslations) ; 
XtOverrideTranslations (farewell,  mytranslations) ; 

As  mentioned  earlier,  you  will  find  it  more  convenient  to  place  the  translation  table  in  the 
application-defaults  file  until  the  last  minute,  because  this  allows  changes  without  recompil 
ing  the  source. 


2.5  More  About  Resources 

You  now  have  read  about  enough  techniques  to  construct  an  application  that  uses  widgets  for 
its  user  interface  and  connects  the  widgets  to  application  code.  However,  in  order  to  really 
take  advantage  of  any  widget  class,  you  have  to  learn  about  its  resources,  so  that  you  can  set 
the  desired  resources  in  the  application-defaults  file. 

A  class  defines  its  own  resources,  and  also  inherits  the  resources  of  all  its  superclasses.  For 
example,  Command  supports  not  only  its  own  resources  but  also  the  resources  of  its  super 
classes,  Label  and  Core.  The  documentation  for  a  widget  class  may  describe  only  the 
resources  for  that  class  and  list  the  name  of  the  superclass  (which  you  can  then  look  up),  or  it 
may  list  all  the  resources  of  that  class  and  all  superclasses. 
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2.5.1    Setting  and  Getting  Resources  from  the  Application 

The  application  can  change  resources  of  existing  widgets.  This  can  be  very  useful,  but  you 
should  be  aware  that  setting  a  resource  from  the  application  wipes  out  the  user-specified 
value  for  that  same  resource  (if  any),  unless  you  first  query  the  resource,  and  then  set  it  based 
on  its  earlier  value.  This  section  describes  first  how  to  set  resources  and  then  how  to  get 
them. 

To  set  and  get  resources,  you  use  the  Xt  functions  xtSet Values  and  xtGetValues. 
Each  of  these  functions  takes  three  arguments:  a  widget,  an  array  of  Arg  structures  in  which 
the  resource  name/value  pair  are  stored,  and  a  count  of  the  number  of  argument  pairs  in  the 
array. 

Setting  resources  is  often  used  for  resetting  strings  in  Label  widgets.  Example  2-9  shows  the 
code  needed  to  change  the  string  of  a  Label  widget — this  will  work  any  time  after  the  widget 
has  been  created,  either  before  or  after  the  widget  is  realized. 

Example  2-9.  Code  fragment  to  set  a  widget  resource 

Arg   arg; 

static  String  new_label  =  "Hi  there." 


XtSetArg(arg,  XtNlabel,  new_label) ; 
XtSetValues (w,  &arg,  1); 

There  are  several  things  in  this  code  segment  likely  to  be  new  to  you.  The  types  Arg  and 
String  are  defined  in  <X11  /Intrinsic. h>.  String  is  defined  as  char  *,  and  Arg  is 
defined  as  a  structure  containing  the  name  and  value  pair  that  defines  a  resource: 

typedef  struct  { 

String       name; 

XtArgVal  value; 

}    Arg,    *ArgList; 

The  definition  of  XtArgVal  differs  depending  on  architecture — its  purpose  is  precisely  to 
make  code  portable  between  architectures  with  different  byte  sizes.  Its  use  in  application 
code  will  be  demonstrated  in  Section  3.7.1.  xt  Set  Arg  is  a  macro  that  makes  it  more  con 
venient  to  set  the  two  members  of  the  Arg  structure.  If  desired,  you  can  also  set  the  Arg 
structure  members  like  any  other  C  structure  by  using  the  .  or  ->  syntax. 

Note  that  the  first  member  of  Arg  is  of  type  String,  yet  in  Example  2-9  that  string  was 
specified  in  xt  Set  Arg  using  the  symbolic  constant  XtNlabel.  The  resource  name  and 
class  are  stored  in  symbolic  constants  to  improve  compile-time  checking.  If  you  misspell  a 
symbolic  constant,  the  compiler  will  note  the  error.  If  you  misspell  a  string,  on  the  other 
hand,  the  error  would  go  unnoticed  by  the  compiler  and  cause  a  run-time  error  such  as  a  core 
dump.  Therefore,  all  resource  names  are  specified  using  constants  of  the  form  xtN/iame, 
where  name  is  the  resource  name.  The  include  file  <XlllStringDefs.h>  and  the  public 
include  files  for  each  widget  (such  as  <X1  II Label. h>)  contain  the  resource  name  constant 
definitions. 
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xtSetValues  is  the  call  that  actually  changes  the  widget  resource.  You  pass  it  the  widget 
to  be  reconfigured,  a  list  of  Arg  structures,  and  the  length  of  the  list.  Example  2-9  sets  only 
one  resource,  so  the  list  length  is  1. 

XtSetValues  can  set  any  number  of  resources  of  a  single  widget  instance.  Example  2-10 
shows  the  code  necessary  to  set  two  resources. 

Example  2-10.  Code  fragment  to  set  multiple  resources  of  a  widget 

static  String  new_label  =  "Hi  there." 
Arg  args [3] ; 
int  i; 


i  =  0; 

XtSetArg(args[i] ,  XtNwidth,  100); 
XtSetArg(args[i] ,  XtNlabel,  new_label) 
XtSetValues (w,  args,  i); 

Note  that  the  counter  i  cannot  be  incremented  inside  the  xt  Set  Arg  macro,  because  that 
macro  references  its  first  argument  twice.  Therefore,  it  is  customarily  incremented  on  the 
end  of  the  same  line,  so  that  additional  resource  settings  can  easily  be  added. 

It  is  also  useful  to  be  able  to  get  the  current  value  of  a  widget  resource.  Perhaps  the  most 
common  use  of  this  is  to  get  the  current  size  or  position  of  a  widget  Another  use  is  in  finding 
out  what  value  the  user  has  specified  for  a  particular  resource.  Because  C-language  argu 
ments  are  passed  by  value,  and  some  resource  values  are  not  single  values  but  strings  or  func 
tion  pointers,  it  is  a  little  more  difficult  to  get  widget  values  than  to  set  them.  Example  2-11 
shows  how  to  get  a  pointer  to  the  current  string  in  a  Label  widget 

Example  2-11.  Code  fragment  to  get  a  widget  resource 
tdefine   MAXLEN    256 


Widget  hello; 

Arg  arg; 

char  userstring [MAXLEN] ; 

char  *p; 


/*  Label  widget  named  hello  created  here.  */ 
XtSetArg(arg,  XtNlabel,  &p)  ; 
XtGetValues (hello,  &arg,  1); 
strcpy (userstring,  p) ; 

The  Xt  Set  Arg  call  sets  the  XtNlabel  argument  in  the  argument  list  to  a  pointer  to  the 
application  variable  p  (which  itself  is  a  pointer),  and  then  XtGetValues  is  called,  which 
sets  the  pointer  p  to  point  to  the  widget's  resource.  The  result  is  that  the  application  knows 
the  value  of  p  and  p  points  to  the  resource. 
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This  code  may  seem  nonintuiti ve.  However,  since  this  method  is  the  same  for  any  resource, 
you  can  just  remember  it  or  look  it  up  even  if  you  don't  understand  it 

Note  however  that  some  resources  are  not  designed  to  be  queried.  For  example,  translation 
tables  and  callbacks  are  compiled  into  an  internal  representation,  so  it  is  pointless  to  try  to 
read  them. 


2.5.2   Core  Resources 


All  widgets  are  subclasses  of  Core.  Therefore,  the  resources  of  the  Core  class  are  available 
for  all  widgets.  Table  2-1  shows  the  Core  resources. 

For  each  resource,  both  name  and  class  strings  are  defined.  Class  strings  are  often  the  same 
as  the  corresponding  resource  name  string,  but  with  the  prefix  xtc  instead  of  xtN,  and  with 
the  first  letter  of  the  resource  name  capitalized. 

The  use  of  resource  classes  allows  the  user  or  the  application  programmer  to  specify  that  all 
resources  of  a  particular  type  be  given  the  specified  value. 

Table  2-1.  Core  resources 


Name 

Class 

Type 

Default 

XtNx 

XtCPosition 

Position 

0 

XtNy 

XtCPosition 

Position 

0 

XtNwidth 

XtCWidth 

Dimension 

0 

XtNheight 

XtCHeight 

Dimension 

0 

XtNscreen 

XtCScreen 

Pointer 

from 

DISPLAY 

XtNcolormap 

XtCColormap 

Pointer 

from 

parent 

XtNdepth 

XtCDepth 

int 

from 

parent 

XtNbackground 

XtCBackground 

Pixel 

White 

XtNbackgroundPixmap 

XtCPixmap 

Pixmap 

NULL 

XtNborderWidth 

XtCBorderWidth 

Dimension 

1 

XtNborderColor 

XtCBorderColor 

Pixel 

Black 

XtNborderPixmap 

XtCPixmap 

Pixmap 

NULL 

XtNtranslations 

XtCTranslations 

Xt  Translations 

NULL 

XtNaccelerators 

XtCAccelerators 

Xt  Translations 

NULL 

XtNmappedWhenManaged 

XtCMappedWhenManaged 

Boolean 

TRUE 

XtNdestroyCallback 

XtCCallback 

Pointer 

NULL 

XtNsensitive 

XtCSensitive 

Boolean 

TRUE 

Xt  Nance  storSensitive 

XtCSensitive 

Boolean 

TRUE 

The  fact  that  size  and  position  are  resources  of  all  widgets  means  that  your  application- 
defaults  file  can  control  the  layout  of  the  application.  You  should  always  resize  widgets  by 


52 


X  Toolkit  Intrinsics  Programming  Manual 


setting  these  resources — never  resize  or  move  a  widget's  window  using  Xlib  calls  since  this 
would  make  Xt's  knowledge  of  window  geometries  inaccurate.  Nor  should  you  use  the  Xt 
functions  XtConf  igureWidget,  XtMoveWidget,  or  XtResizeWidget  from  the 
application.  These  routines  are  intended  to  be  used  only  by  geometry-managing  composite 
widgets. 

The  XtNscreen,  XtNcolormap  and  xtNdepth  resources  hold  the  default  screen, 
colormap,  and  depth  (the  number  of  bits  per  pixel  used  for  indexing  colors  in  the  colormap). 
The  top-level  shell  widget  gets  the  screen  from  the  DISPLAY  environment  variable  or 
-display  command  line  option;  other  widgets  inherit  that  value  and  cannot  change  it.  The 
top-level  shell  widget  gets  the  root  window's  depth  and  default  colormap;  other  widgets 
inherit  their  parent's  depth  and  colormap,  so  unless  an  intervening  widget  has  set  a  different 
depth  or  colormap,  a  widget  should  have  the  root  window's  depth  and  colormap  by  default. 

The  XtNbackground,  XtNbackgroundPixmap,  XtNborderWidth,  Xt- 
NborderColor,  xtNborderPixmap  widget  resources  control  the  background  and  bor 
der  of  the  window  created  by  a  widget  The  background  and  border  of  a  window  are  main 
tained  by  the  X  server,  and  setting  these  resources  causes  an  immediate  change  in  the  win 
dow  on  the  screen.  You  can  set  either  a  background  color  or  a  background  pixmap,  but  not 
both.  Whichever  is  set  later  takes  priority.  The  same  applies  to  the  border. 

A  pixmap  is  similar  to  a  window  but  is  off-screen.  It  is  an  array  of  pixels.  When  used  as  a 
background  or  border,  a  pixmap  is  tiled  by  laying  out  multiple  copies  of  it  side  by  side,  for 
the  purpose  of  patterning.  Pixmaps  are  also  used  for  icon  patterns,  in  drawing,  and  as  a  tem 
porary  drawing  surface  later  copied  to  a  window. 

The  XtNbackground  and  xtNborderColor  resources  can  be  set  using  either  a  color 
name  string  or  a  hexadecimal  color  specification.  (See  Appendix  C,  Specifying  Fonts  and 
Colors,  for  more  information  on  acceptable  forms  of  color  specification.) 

The  value  of  the  XtNbackgroundPixmap  and  XtNborderPixmap  resources  should 
be  a  pathname  to  a  file  containing  the  bitmap,  or  to  a  bitmap  created  in  your  program.  On 
UNIX  systems,  standard  X  bitmaps  are  stored  in  the  directory  /usr/include/XU /bitmaps.  See 
Appendix  F  in  Volume  Three,  X  Window  System  User's  Guide,  for  information  on  these  stan 
dard  bitmaps. 

xtNtranslations  is  the  resource  that  contains  the  translation  table  described  in  Section 
2.4.2  above.  As  we  demonstrated  there,  by  setting  this  resource  you  can  change  the  events 
that  trigger  a  widget's  actions  or  the  actions  your  application  has  registered,  xt- 
Naccelerators  contains  an  accelerator  table.  (Accelerators  are  an  extended  form  of 
translations  that  allow  events  in  one  widget  to  be  bound  to  actions  in  another.) 

xtNmappedWhenManaged  is  a  resource  used  by  geometry-managing  widgets  to  specify 
whether  a  widget  should  be  eligible  for  display  (i.e.,  mapped  to  the  screen)  as  soon  as  it  is 
placed  under  parental  geometry  management,  or  whether  this  should  not  happen  until  some 
later  time.  We'll  talk  more  about  this  concept  in  Chapter  11,  Geometry  Management. 

The  xtNdestroyCallback  resource,  as  described  in  Section  2.4.1  above,  lets  you  pro 
vide  an  application  function  to  be  called  when  a  widget  is  destroyed.  This  is  infrequently 
used,  since  the  Toolkit  normally  handles  the  job  of  freeing  widget  data  structures  and  any 
server  resources. 
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The  xtNsensitive  resource  controls  whether  a  widget  responds  to  user  input.  This 
allows  you  to  turn  on  or  off  user  input  in  a  certain  widget  at  will.  For  example,  if  you  have  a 
Command  widget  whose  command  is  not  allowed  at  certain  times,  you  would  set  xt 
Nsensitive  to  FALSE  during  the  period  the  command  is  not  allowed.  The  Command 
widget  changes  its  own  look  to  indicate  that  it  is  invalid. 

The  XtNancestorSensitive  resource  specifies  whether  the  widget's  parent  (or  earlier 
ancestor)  is  sensitive.  Sensitivity  is  propagated  downward,  such  that  if  any  ancestor  is  insen 
sitive,  a  widget  is  insensitive.  This  resource  will  often  be  hardcoded  by  the  application,  since 
if  set  incorrectly  by  the  user,  it  could  make  the  application  inoperable. 

2.5.3   Other  Inherited  Resources 

Besides  the  resources  inherited  from  Core,  a  widget  inherits  resources  from  each  of  its  super 
classes.  For  example,  the  Command  widget  used  in  xfarewell  inherits  resources  from  the 
Label  widget  class.  As  shown  in  Table  2-2,  these  include,  in  addition  to  the  label  itself,  a 
font,  a  foreground  color,  spacing  above  and  below  the  string,  and  a  value  specifying  how  the 
string  should  be  placed  in  the  widget  (Note  that  this  list  is  not  complete.  There  are  other 
resources  not  shown.) 

Table  2-2.  Label  resources 


Name 

Class 

Type 

Default 

XtNfont 

XtCFont 

XFontStruct* 

XtDefaultFont 

XtN  foreground 

XtCForeground 

Pixel 

Xt  Default  Foreground 

XtNinternalHeight 

XtCHeight 

Dimension 

2 

XtNinternalWidth 

XtCWidth 

Dimension 

A 

XtNjustify 

XtCJustify 

XtJustify 

XtJustifyCenter 

XtNlabel 

XtCLabel 

String 

NULL 

It  is  a  worthwhile  exercise  to  experiment  with  the  resources  available  to  an  application 
through  its  widgets,  even  with  such  a  simple  example  as  xgoodbye  or  xfarewell .  For 
example,  consider  the  resource  settings  for  xfarewell  shown  in  Example  2-12.* 

Example  2-12.  Alternate  resource  settings  for  xfarewell 

i 

!  Core  resources 
i 

!  The  following  two  lines  don't  work,  but  demonstrate  a  point 
*farewell.x:  100 
*farewell.y:  100 

!  Even  though  it  syntactically  applies  to  all  widgets  in  the 
!  application,  the  borderWidth  resource  is  only  used  by  the 


*See  Appendix  C,  Specifying  Fonts  and  Colors,  for  more  information  on  the  font  resource  specification  shown  in  the 
example. 
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Example  2-1 2.  Alternate  resource  settings  for  xfarewell  (continued) 

!  Shell  widget, 
t 

*borderWidth:  10 

*farewell. width:  200 

*farewell. height :  100 

* farewell. background? ixmap:  /usr/include/Xll/bitmaps/root_weave 

*f arewell . translations :  #override\n\ 

Shift <BtnlUp>:     quit()\n\ 

<BtnlDown>,<BtnlUp>:    confirm () 

!  Label  resources 
i 

*f arewell . foreground:  white 

*farewell.font :  helvB024 

*f arewell. label:   Click  on  me. 

Note  that  an  exclamation  point  (!)  in  column  zero  begins  a  comment  line  in  a  resource  file. 

These  settings  can  either  be  placed  in  an  Xdefaults  file  in  your  home  directory,  or  you  can 
save  them  in  any  file  you  like  and  load  them  into  the  server  using  the  xrdb  client,  as  follows: 

xrdb   -merge    resource_file 

(If  you  want  to  repeat  the  experiment  with  different  values,  you  should  be  aware  that  once 
resources  are  set  with  xrdb,  they  remain  in  effect.  Subsequent  invocations  of  xrdb  -merge 
will  replace  settings  for  the  same  resources,  but  won't  remove  any  others  that  were  set 
before.  To  start  with  a  clean  slate,  use  xrdb  -load  instead.  Note,  however,  that  this  will 
replace  all  of  your  resource  settings,  including  those  for  other  applications.  See  Chapter  9  of 
Volume  Three,  X  Window  System  User's  Guide,  for  more  information  on  using  xrdb.  See 
Chapter  9  of  this  book  for  more  information  on  other  possible  sources  of  resource  settings.) 

The  window  that  results  when  you  run  xfarewell  with  these  resource  settings  is  shown  in  Fig 
ure  2- 13. 

If  you  spend  some  time  playing  with  different  resource  settings,  you  will  find  some  unex 
pected  behavior.  For  instance,  setting  the  value  of  the  x  and  y  resources  has  no  effect. 
Regardless  of  their  value,  the  xfarewell  application  is  simply  placed  at  the  current  pointer 
position. 

The  reason  for  this  is  that  these  resources  set  the  widget  position  relative  to  its  parent,  and 
since  the  farewell  widget  is  a  child  of  an  identically  sized  Shell  widget,  they  are  mean 
ingless.  In  its  geometry-management  policy,  the  shell  widget  ignores  the  value  of  these 
resources. 

If  instead  you  use  the  x  and  y  resources  to  try  to  set  the  position  of  the  application: 

xfarewell.x:   100 
xfarewell.y:   100 

they  are  ignored  also,  for  a  similar  reason.  It  is  customary  for  the  window  manager  to  assert 
control  over  the  position  of  the  main  application  window  (in  this  case  the  farewell 
widget),  and  take  the  value  of  these  resources,  whether  set  by  the  application  or  by  the  user, 
simply  as  "hints"  to  the  desired  behavior.  There  is  no  guarantee  that  the  window  manager 
will  honor  these  hints.  The  application  is  generally  free  to  move  widgets  within  its  own 
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Figure  2-13.  xfarewell  run  with  new  resource  settings 

window,  but  not  to  move  itself.  The  basic  X  philosophy  is  that  the  user  (through  the  window 
manager),  not  the  application,  should  be  in  control.  (Kill  the  window  manager,  or  run  a  win 
dow  manager  than  honors  application  position  hints,  and  the  resource  specifications  shown 
just  above  will  work.) 

Likewise,  you  will  find  that  specifying: 

*farewell.borderWidth:   10 

has  no  effect,  while: 

*borderWidth:    10 

does.  The  reason  for  this  behavior  is  that  while  the  Command  widget  inherits  the  border- 
width  resource,  it  does  nothing  with  its  value.  Only  top-level  shell  widgets  use  the 
borderwidth  resource  to  set  the  border  width  of  their  window.  Just  because  a  resource  is 
inherited  by  a  widget  does  not  mean  that  the  widget's  methods  do  anything  to  use  its  value. 

Another  surprising  fact  is  that  once  you  set  the  foreground  resource  to  white,  the  Com 
mand  widget's  set  action,  which  highlights  the  widget's  border,  no  longer  appears  to  work. 
This  is  because  the  highlighting  is  done  by  drawing  in  the  foreground  color  (now  white), 
while  the  unhighlighting  is  drawn  in  the  background  color  (also  still  white,  despite  the  use  of 
the  background  pixmap  for  the  body  of  the  window).  To  make  highlighting  work,  you  must 
make  sure  that  the  foreground  and  background  colors  are  different.  Adding  the  line: 

*farewell .background:    black 
will  do  the  trick. 
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The  cautionary  point  is  that  there  may  be  unexpected  interactions  between  resources  in 
widget  code.  Like  programs  in  general,  widgets  do  what  you  say,  not  what  you  mean.  A 
well-designed  widget  will  minimize  ill  effects,  but  given  the  amount  of  customization  that  is 
possible,  it  may  take  some  time  to  uncover  all  the  possible  pitfalls.  Unfortunately,  the  docu 
mentation  for  most  existing  widgets  doesn't  always  do  a  good  job  of  explaining  how 
resources  are  used  inside  the  widget. 
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More  Widget 
Programming  Techniques 


This  chapter  describes  how  to  use  some  of  the  more  complex  widgets  found 
in  applications,  including  composite  widgets,  constraint  widgets,  and  pop  ups. 
It  also  describes  how  to  define  application  resources  and  command-line 
options,  and  how  to  hardcode  the  value  of  widget  resources  when  you  create 
a  widget. 
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The  techniques  described  in  Chapter  2,  Introduction  to  the  X  Toolkit,  will  get  you  started  on 
the  path  to  writing  applications.  But  there  are  more  tools  at  your  disposal.  This  chapter 
describes  the  following  techniques: 

•  How  to  use  composite  widgets  to  create  a  hierarchy  of  widgets  in  an  application.  This 
section  describes  how  to  use  different  kinds  of  composite  widgets  so  that  the  application 
can  be  resized  and  still  look  good.  It  also  shows  how  to  set  resources  for  a  widget  hier 
archy  in  the  application  defaults  file. 

•  How  to  use  pop-up  widgets  such  as  dialog  boxes  and  menus. 

•  How  to  use  callback  lists  (instead  of  single  callback  functions),  and  how  to  pass  data  to 
callback  functions. 

•  How  to  make  your  applications  easier  for  the  user  to  customize  by  defining  application- 
specific  resources  and  command-line  arguments. 

•  How  to  hardcode  the  value  of  resources  when  you  create  a  widget. 

•  How  to  use  application  contexts,  which  you  must  use  to  make  applications  portable  to 
some  systems. 


3.1   Using  Composite  Widgets 

The  examples  in  Chapter  2,  Introduction  to  the  X  Toolkit,  were  atypical  because  they  con 
tained  only  one  widget.  Any  real  application  has  several  widgets,  and  therefore  needs  some 
way  of  laying  them  out  in  case  the  application  is  resized.  Therefore,  the  first  widget  you  cre 
ate  after  calling  xt  Initialize  is  usually  a  composite  widget,  whose  job  it  is  to  manage 
the  layout  of  a  group  of  child  widgets.  The  parent  of  this  composite  widget  is  the  Shell 
widget  created  by  xtlnitialize,  usually  called  topLevel. 

Example  3-1  shows  a  small  application,  xboxl,  that  creates  two  Command  widgets  contained 
in  a  Box  widget. 
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Example  3-1.  xboxl.c:  complete  code 

/* 

*  xbox.c  -  simple  button  box 
*/ 

/* 

*  So  that  we  can  use  fprintf: 
*/ 

#include  <stdio.h> 

/* 

*  Standard  Toolkit  include  files: 
V 

#include  <Xll/Intrinsic ,h> 
#include  <Xll/StringDef s ,h> 

/* 

*  Public  include  files  for  widgets  used  in  this  file. 
*/ 

#ifdef  X11R4 

tinclude  <Xll/Xaw/Command.h> 

#include  <Xll/Xaw/Box.h> 

#else 

tinclude  <X1 1 /Command .h> 

#include  <Xll/Box.h> 

tendif  /*  X11R4  */ 

/* 

*  quit  button  callback  function 
*/ 

/*ARGSUSED*/ 

void  Quit (w,  client_data,  call_data) 

Widget  w; 

caddr_t  client_data,  call_data; 

{ 

exit (0)  ; 
} 

/* 

*  "Press  me!"  button  callback  function 
*/ 

/*ARGSUSED*/ 

void  PressMe(w,  client_data,  call_data) 

Widget  w; 

caddr_t  client_data,  call_data; 

{ 

fprintf (stderr,  "Thankyou ! \n") ; 
} 

main(argc,  argv) 
int  argc; 
char  **argv; 
{ 

Widget  box,  quit,  pressme,  topLevel; 

topLevel  =  Xtlnitialize ( 

argv[0],  /*  application  name  */ 

"XBoxl",  /*  application  class  name  */ 

NULL,  /*  application  resources  (not  used)  */ 

0,  /*  application  resource  count  */ 

Sargc,  /*  command  line  argument  count  */ 
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Example  3-1.  xboxl.c:  complete  code  (continued) 

argv) ;  /*   command-line   string   */ 

box   =   XtCreateManagedWidget ( 

"box",  /*    widget   name    */ 

boxWidgetClass,  /*   widget   class    */ 

topLevel,  /*   parent   widget*/ 

NULL,  / 

0  /: 


argument  list*/ 
arglist  size  */ 


quit  =  XtCreateManagedWidget ( 

"quit",  /*  widget  name  */ 

commandWidgetClass,     /*  widget  class  */ 
box,  /*  parent  widget*/ 

NULL,  /' 

0  / 


argument  list*/ 
arglist  size  */ 


pressme  =  XtCreateManagedWidget ( 


"pressme", 
commandWidget Class , 
box, 

NULL, 
0 


/*  widget  name  */ 

/*  widget  class  */ 

/*  parent  widget*/ 

/*  argument  list*/ 

/*  arglist  size  */ 


XtAddCallback (quit,  XtNcallback,  Quit,  0) ; 
XtAddCallback (pressme,  XtNcallback,  PressMe,  0); 

XtRealizeWidget (topLevel) ; 
XtMainLoop ( ) ; 

Example  3-1  creates  a  Box  widget  called  box  as  a  child  of  topLevel,  and  then  creates 
each  Command  widget  as  a  child  of  box.  Notice  how  the  parent  argument  of  each  genera 
tion  of  widgets  is  used.  Also  notice  that  the  Shell  widget  topLevel  is  exactly  the  same 
size  as  box  and  therefore  is  not  visible. 

If  your  application  creates  many  children  for  a  single  widget,  it  may  be  preferable  to  create 
the  children  with  xtCreateWidget,  and  then  manage  all  the  children  of  that  parent  with 
a  single  call  to  XtManageChildren  (instead  of  calling  XtCreateManagedWidget 
for  each  child). 


3.1.1    Setting  Resources  for  an  Instance  Hierarchy 

You  have  already  seen  how  an  application-defaults  file  can  set  the  string  for  a  Command 
widget  However,  xboxl  contains  two  Command  widgets,  and  a  widget  instance  hierarchy 
that  also  includes  a  Box  widget  It  is  worth  seeing  how  to  set  the  Command  widget  labels  in 
this  new  situation.  (We  will  be  returning  often  to  the  subject  of  setting  resources,  because  it 
is  so  important  to  Toolkit  programming.  Each  time,  new  ideas  will  be  presented.) 
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Example  3-2  shows  an  application-defaults  file  forxboxl. 

Example  3-2.  XBoxl:  application-defaults  file 

*pressme*label :          Press   Me 

*quit*label:     Quit 

*Command*background:    green 

!  The  following  entry  would  place  the  buttons  side  by  side,  regardless 

!  of  font.   No  setting  makes  the  box  wider  than  all  children  side  by 

!  side  or  narrower  than  the  widest  child. 

!*box. width:   1000 

Figure  3-1  shows  how  the  application  looks  on  the  screen. 


Quit 

Press  Me 

Figure  3-1.  xboxl:  appearance  on  the  screen 

When  an  application  contains  multiple  widgets  of  the  same  class,  resource  specifications  can 
either  identify  individual  widget  instances  by  name  or  can  use  wildcards  or  widget  class 
names  to  reference  more  than  one  widget  The  first  two  entries  in  the  example  identify  the 
pressme  and  quit  widgets  by  instance  name.  The  third  entry  uses  the  class  name  Com 
mand  to  set  the  background  of  both  Command  widgets  (but  not  the  Box  widget)  to  the  color 
green.  This  line  shows  that  resources  of  groups  of  widgets  can  be  set  at  the  same  time.  (The 
second  asterisk  in  each  specification  is  equivalent  to  a  dot,  because  an  asterisk  matches  zero 
or  more  intervening  instances  or  classes.)  Because  we've  used  the  class  name,  the  back 
ground  color  of  all  Command  widgets  in  the  application,  even  ones  we  add  later,  will  be 
green.  To  make  the  Box  widget  green  as  well,  we  could  have  used  an  even  more  general 
specification  such  as  *background:  green. 

Note  that  you  need  to  know  the  instance  name  for  each  widget  in  the  application  in  order  to 
set  its  resources  individually.  This  is  true  for  all  resource  files,  including  the  ones  customized 
by  the  user.  Therefore,  in  the  documentation  for  your  application,  be  sure  to  include  the 
name  and  class  of  each  widget  in  your  instance  hierarchy.  To  be  thorough,  also  include  a 
description  of  the  resources  of  each  class,  and  specify  which  resources  the  user  can  custom 
ize. 

The  first  argument  of  each  xtCreateManagedWidget  call  is  the  widget  instance  name. 
This  name  can  be  used  to  set  resources  for  this  widget  from  the  resource  databases.  This  is 
often  the  same  name  as  the  variable  of  type  widget  that  holds  the  widget  ID.  This  lexical 
connection  is  not  mandatory,  but  it  reduces  confusion  by  helping  you  to  remember  the  con 
nection  between  entries  in  the  application-defaults  file  and  the  widget  instances  in  the  appli 
cation. 
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3.1.2   Geometry  Management  in  Practice 

Build  and  run  xboxl  as  described  in  Section  3.1,  then  try  resizing  it  to  see  how  the  Box 
widget  deals  with  various  geometries.  The  two  possibilities  are  shown  in  Figure  3-2. 


Quit 

Press  Me 

Quit 

Press  Me 

Figure  3-2.  Two  configurations  of  xboxl 

When  you  resize  the  xboxl  application,  you  may  notice  that  although  the  Box  widget  initially 
places  the  widgets  one  above  the  other,  upon  resizing  it  places  them  side  by  side  if  there  is 
room.  To  have  the  buttons  placed  side-by-side  by  default,  set  the  width  of  the  button  box  to  a 
value  greater  than  the  sum  of  the  widths  of  the  enclosed  Command  widgets.  The  com- 
mented-out  entry  in  Example  3-2  would  do  the  trick. 

Notice  also  that  the  effects  of  resizing  from  the  window  manager  and  resizing  by  setting  the 
xboxl. box. width  resource  are  quite  different.  Using  the  window  manager,  you  can 
resize  the  box  to  be  smaller  than  the  buttons,  causing  them  to  be  clipped,  or  to  be  far  larger 
than  needed,  so  that  they  sit  at  the  upper-right  corner  of  a  large  window.  Using  resource 
specifications,  you  can  make  the  box  large  enough  to  hold  the  buttons  side-by-side,  but  no 
larger.  You  cannot  make  it  narrower  than  the  width  of  the  widest  button,  or  shorter  than  the 
height  of  a  button. 

Every  widget's  size  and  position  is  ultimately  under  the  control  of  the  window  manager.  A 
box  widget  may  do  some  basic  sanity  checking  on  values  specified  in  the  resource  files 
before  it  uses  them.  But  the  window  manager  can  override  anything  the  widget  or  the  appli 
cation  does. 

What  happens  when  the  user  resizes  an  application  is  only  part  of  the  picture.  The  applica 
tion  itself  may  need  to  resize  one  of  its  widgets  in  order  to  display  more  widgets.  Or  the 
application  may  tell  a  widget  to  display  more  data  and  the  widget  will  have  to  ask  its  parent 
to  be  resized. 

For  example,  what  happens  when  the  application  changes  the  string  in  one  of  the  Command 
widgets  while  the  application  is  displayed? 

The  Command  widget  attempts  to  resize  itself  to  display  the  current  string,  by  asking  its  par 
ent  for  permission.  Whether  this  request  is  granted  depends  on  the  position  of  the  widget  in 
the  instance  hierarchy,  the  resizing  policy  imposed  by  each  composite  widget  in  the  hier 
archy,  and  the  window  manager.  This  is  because  each  widget,  from  the  Command  widget  on 
up,  negotiates  with  its  parent  when  the  Command  widget  requests  a  new  size.  If  the  Com 
mand  widget  already  has  enough  space,  it  changes  the  string  and  no  geometry  change  is  nec 
essary.  But  if  the  Command  widget  tries  to  change  size  to  accommodate  the  new  string 
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(larger  or  smaller),  the  Box  widget  must  approve  this  change.  Since  the  Box  widget  is 
already  the  same  size  as  the  Shell  widget,  Box  can't  get  any  larger  without  asking  Shell.  The 
Shell  widget  is  responsible  for  negotiating  with  the  window  manager.  Most  window  manag 
ers  will  not  allow  an  application  to  resize  itself,  because  windows  should  be  resized  only  in 
response  to  a  user  request  through  the  window  manager.  Therefore,  the  Box  widget  will 
reject  the  resize  request  unless  it  makes  the  Command  widget  smaller. 

Fortunately,  all  this  negotiation  is  done  by  the  widgets  themselves.  The  application  doesn't 
need  to  do  anything.  However,  you  should  be  aware  that  any  widget  resource  change  that 
results  in  a  size  change  won't  work  unless  there  is  enough  room  in  the  application  for  the 
change  to  be  granted  without  resizing  the  top-level  window. 

Overall,  the  Box  widget  is  useful  for  managing  Command  widgets,  because  its  simple  rules 
work  nicely  when  the  children  are  similarly  sized  widgets.*  However,  it  can't  cope  with 
widgets  that  are  of  radically  different  geometries.  Box's  decisions  about  where  to  place  the 
widgets  are  inappropriate.  Figure  3-3  shows  the  results  upon  resizing  of  a  Box  widget  that  is 
attempting  to  manage  two  Scroll  widgets  and  a  BitmapEdit  widget  t 

Because  geometry  management  is  so  complex,  there  are  several  different  types  of  composite 
widgets  in  most  widget  sets,  each  with  different  rules  about  how  it  places  children.  Many 
widget  sets  have  a  widget  specifically  designed  to  place  scrollbars  next  to  a  main  window. 

Of  course,  applications  are  not  limited  to  using  only  one  composite  widget  It  is  quite  com 
mon  for  the  application's  main  window  to  be  a  large  composite  widget  which  contains  sev 
eral  smaller  composite  widgets,  each  of  which  in  turn  contains  certain  groups  of  related 
widgets.  Figure  3-4  shows  the  xmh  application  and  the  instance  hierarchy  used  to  create  it. 
The  top  composite  widget  in  xmh  is  of  the  Athena  VPaned  class  (renamed  Paned  in  Release 
4).  The  VPaned  widget  creates  several  horizontal  panels,  or  panes,  one  for  each  child,  with  a 
Grip  widget  positioned  on  the  line  between  each  pane.  This  Grip  is  used  to  change  the  rela 
tive  size  of  the  pane.  Each  pane  contains  a  different  functional  area  of  the  application.  The 
panes  that  appear  to  contain  Command  widgets  actually  each  contain  a  single  Box,  which  in 
turn  contains  Command  widgets.  You'll  need  to  design  the  layout  of  widgets  in  your  applica 
tion,  decide  where  in  the  instance  hierarchy  to  place  composite  widgets,  and  experiment  to 
find  out  which  composite  widgets  provide  the  best  appearance  when  the  application  is 
resized. 

One  of  your  tools  in  arranging  child  widgets  is  a  subclass  of  composite  widgets  called  con 
straint  widgets. 


*From  a  user-interface  point  of  view,  however,  one  weakness  of  any  widget  like  Box  is  that  resizing  leaves  the  Com 
mand  widgets  in  new  locations  where  the  user  may  not  expect  to  find  them.  It  is  annoying  to  have  to  search  a  box  of 
buttons  for  the  button  you  want 

tThe  BitmapEdit  widget  is  not  pan  of  the  Athena  widget  set  It  is  used  in  Chapter  4,  An  Example  Application,  and 
written  from  scratch  in  Chapter  5,  Inside  a  Widget  and  Chapter  6,  Basic  Widget  Methods. 
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Print  arraij"||Quit 


Figure  3-3.  Results  upon  resize  of  Scroll  widgets  inside  a  Box  widget 

3.2  Using  Constraint  Widgets 

Constraint  widgets,  like  composite  widgets,  manage  the  layout  of  children.  The  difference  is 
that  constraint  widgets  let  the  application  provide  layout  information  for  each  child.  This  is  a 
more  powerful  way  to  arrange  children  because  it  allows  you  to  provide  different  rules  for 
how  each  child  will  be  laid  out 
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Folder  |  [Table  of  Contents] [jjessagej  [Sequence] [Vieu] | OptionsJ 


protocol  1 1 xl ib  1 1 xl ibbook  |  [xneus] 


inboxtall 


inbox:2 


Date:  Mon,  27  Nov  89  16:19:53  EST 
[From:  adnan  (fldrian  Nye> 
Message- Id:  <8911272120 . Afl07404@sp  i  ke> 
I  To:  adnan 
Subject:  test  message 

This  is  a  test  of  the  emergency  mail  handling  system. 
This  is  only  a  test.  If  this  had  been  a  real  emergency, 
I  it  would  not  have  uorked. 


Shell 


Box 

Label             Box 

Text             Text 

Label            Text 

~T 

J 

1 

I 

\    Command 

|    Command 

Command 

|    Command 

Figure  3-4.  The  xmh  application  and  its  instance  hierarchy 

In  an  application,  you  create  a  constraint  widget  just  as  you  would  any  other  widget.  But  you 
don't  set  resources  of  the  constraint  widget  to  specify  how  each  child  is  laid  out.  Instead,  you 
set  resources  of  each  child  of  the  constraint  widget  Once  any  child  widget  is  placed  under 
the  management  of  a  constraint  widget,  the  child  suddenly  has  the  set  of  resources  defined  by 
the  constraint  widget,  which  controls  its  layout  As  usual,  these  resources  can  be  set  from  the 
application-defaults  file,  from  any  other  resource  database  file,  by  hardcoding  resources  in 
the  application  as  described  in  Section  2.3.4,  or  by  using  Xt  SetValues. 

We'll  demonstrate  how  constraint  widgets  work  by  replacing  the  Box  widget  in  xboxl 
(Example  3-1)  with  an  Athena  Form  widget  (a  constraint  widget).  This  example  is  called 
xbox2  in  the  source  code.  We  won't  show  this  code,  because  the  differences  from  xboxl  are 
slight.  The  only  change  is  that  all  occurrences  of  Box  and  box  are  changed  to  Form  and 
form,  respectively.  The  real  difference  between  xbox2  and  xboxl  lies  in  the  setting  of 
resources  in  the  application-defaults  file. 

The  Form  widget  defines  a  number  of  constraint  resources,  which  to  the  user  appear  to  be 
resources  of  the  child  widgets  managed  by  the  Form.  Looking  at  these  resources  gives  you  a 
good  idea  of  the  kinds  of  things  that  can  be  done  with  constraints. 

•     The  resources  xtNhorizDistance  and  xtNf  romHoriz  specify  the  widget  posi 
tion  in  terms  of  a  specified  number  of  pixels  horizontally  away  from  another  widget  in  the 
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form.  As  an  example,  xtNhorizDistance  could  equal  10  and  xtNf  romHoriz 
could  be  the  widget  ID  of  another  widget  in  the  Form.  The  new  widget  will  always  be 
placed  10  pixels  to  the  right  of  the  widget  defined  in  xtNf  romHoriz,  regardless  of  the 
size  of  the  Form.  If  XtNf  romHoriz  equals  NULL,  then  XtNhorizDistance  is 
measured  from  the  left  edge  of  the  Form. 

•  Similarly,  the  resources  xtNvertDistance  and  XtNf  romVert  specify  the  widget 
position  in  terms  of  a  specified  number  of  pixels  vertically  away  from  another  widget  in 
the  Form.   If  xtNf  romVert  equals  NULL,  then  XtNvertDistance  is  measured 
from  the  top  of  the  Form. 

When  set  in  the  application,  the  values  for  xtNf  romHoriz  and  xtNFromVert  must 
be  widget  IDs.  But  in  the  resource  database,  widget  names  are  used  instead,  since  the 
user  has  no  way  of  knowing  the  actual  widget  ID.  This  is  an  example  of  the  automatic 
type  conversion  built  into  the  resource  manager.  Resource  conversion  is  described  in 
Chapter  9,  Resource  Management  and  Type  Conversion. 

•  The  XtNtop,  XtNbottom,  xtNlef  t,  and  XtNright  resources  tell  the  Form  where 
to  position  the  child  when  the  Form  is  resized.  The  values  of  these  resources  are  speci 
fied  by  the  enum  XtEdgeType,  which  is  defined  in  <XlllForm.h>. 

•  The  values   XtChainTop,  XtChainBottom,  XtChainLeft,  and  XtChain- 
Right  specify  that  a  constant  distance  is  to  be  maintained  from  an  edge  of  the  child  to 
the  top,  bottom,  left,  and  right  edges,  respectively,  of  the  Form. 

•  The  value  xt Rubber  specifies  that  a  proportional  distance  from  the  edge  of  the  child  to 
the  left  or  top  edge  of  the  Form  is  to  be  maintained  when  the  Form  is  resized.  The  pro 
portion  is  determined  from  the  initial  position  of  the  child  and  the  initial  size  of  the  Form. 
Form  provides  a  StringToEdgeType  conversion  to  allow  the  resize  constraints  to  be 
easily  specified  in  a  resource  file. 

The  default  width  of  the  Form  is  the  minimum  width  needed  to  enclose  the  children  after 
computing  their  initial  layout,  with  a  margin  of  xtNdef  aultoistance  at  the  right  and 
bottom  edges.  If  the  Form  is  assigned  a  width  and  height  that  are  too  small  for  the  layout,  the 
children  will  be  clipped  by  the  right  and  bottom  edges  of  the  Form. 

Example  3-3  shows  the  application-defaults  file  fotxbox2. 

Example  3-3.  XBox2:  application-defaults  file 

*pressme*label :    Press  Me 
*quit*label:  Quit 
*Command*background:    green 
*pressme*f romHoriz :    quit 

Notice  that  since  the  instance  names  are  unchanged  from  xboxl  (Example  3-1)  with  the 
exception  that  box  has  been  changed  to  form,  the  first  three  entries  in  the  application- 
defaults  file  are  also  the  same.  But  the  next  entry,  although  appearing  to  affect  a  resource  of 
the  pressme  Command  widget,  is  actually  an  instruction  for  the  Form  widget  about  where 
to  place  the  pressme  widget  relative  to  the  quit  widget  The  effect  of  this  resource  set 
ting  is  shown  in  Figure  3-5.  Note  that  both  the  widgets  referenced  in  a  constraint  must  be 
child  widgets  of  the  same  constraint  widget,  in  this  case  the  Form  widget 
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If  you  run  this  program  you  can  compare  its  behavior  on  resize  with  the  behavior  of  xboxl , 
and  you  can  experiment  with  different  resource  settings  for  the  Form  widget 


horizDistance 


Press  Me 


*pressme.fromHoriz:  quit 


Figure  3-5.  Effect  of  the  Form  XtNfromHoriz  resource 

One  thing  you  will  notice  is  that  the  Form  widget  is  able  to  resize  the  Command  widgets  in 
addition  to  or  instead  of  moving  them  as  Box  did.  This  is  not  a  difference  between  composite 
and  constraint  widgets,  but  simply  between  Box  and  Form.  Both  composite  and  constraint 
widgets  are  allowed  to  both  resize  and  move  their  children,  but  it  is  up  to  the  design  of  each 
widget  class  whether  they  actually  do  so. 

Another  thing  to  note  is  that  if  you  make  an  error  in  setting  the  constraints,  it  is  quite  possible 
to  end  up  with  one  widget  on  top  of  another.  Sometimes  this  can  make  it  appear  that  one  of 
the  widgets  has  completely  disappeared! 


3.3  Using  Pop  Ups 

Pop  ups  are  widgets  that  are  not  visible  until  a  certain  user  command  is  given,  or  a  situation 
arises  in  which  the  program  requires  user  input,  and  even  then  are  visible  for  only  a  short 
period.  The  most  common  examples  of  pop  ups  are  dialog  boxes  and  menus.  In  general,  a 
pop  up  gets  information  from  the  user  and  then  goes  away. 

Pop  ups  are  not  a  kind  of  widget,  but  rather  a  way  of  using  widgets.  Any  widget  can  be  used 
as  a  pop  up.  You  first  create  a  special  parent  widget  called  a  TransientShell  as  a  child  of 
topLevel.  Then  you  create  the  widget  to  appear  in  the  pop  up,  which  may  be  a  simple 
widget  or  a  composite  widget  with  children.  However,  the  TransientShell  widget,  like  top 
Level,  must  have  only  one  child. 
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This  process  sets  up  the  pop-up  widget,  but  does  not  put  it  on  the  screen.  Somewhere  in  your 
code  you  need  to  call  xt Popup  to  pop  up  the  widget,  and  xtPopdown  when  you  want  to 
make  it  invisible  again.  This  is  typically  done  in  callback  or  action  routines. 

The  xbox3  application  shown  in  Example  3-5  adds  a  pop-up  dialog  box  to  xboxl.  The  actual 
widget  popped  up  is  an  Athena  Dialog  widget.  The  Dialog  widget  is  a  widget  designed  to 
prompt  for  auxiliary  input  from  a  user.  For  example,  you  can  use  a  Dialog  widget  when  an 
application  requires  the  user  to  enter  some  information  such  as  a  file  name.  A  Dialog  widget 
is  actually  just  a  special  case  of  the  Form  widget.  It  provides  a  convenient  way  to  create  a 
"preconfigured  form"  useful  for  dialog  boxes. 

The  typical  Dialog  widget  contains  three  areas.  The  first  line  contains  a  Label  widget  provid 
ing  a  description  of  the  function  of  the  Dialog  widget,  for  example,  the  string  "Filename:". 
The  second  line  contains  a  Text  widget  into  which  the  user  types  input.  The  third  line  can 
contain  one  or  more  Command  widgets  that  let  the  user  confirm  or  cancel  the  Dialog  input. 
The  class  variable  for  the  Dialog  widget  is  dialogWidgetClass. 

Figure  3-6  shows  the  appearance  of  xbox3  when  the  Dialog  widget  is  popped  up. 


Quit 


Pres; 


Enter  Text  Below: 


Dialog  Done 


Figure  3-6.  xboxS:  popping  up  a  Dialog  widget 

Note  that  without  proper  resource  settings  in  the  application-defaults  file,  the  text  entry 
widget  will  not  appear,  and  the  buttons  will  have  different  text  in  them.  Example  3-4  shows 
the  required  application-defaults  file. 

Example  3-4.  xbox3:  application-defaults  file 

*value: 

*pressme*label:         Press  Me 

*quit*label:     Quit 

*dialog*label:  Enter   Text    Below: 

*dialog*Command* label:    Dialog   Done 
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The  *  value :  resource  setting  tells  the  Dialog  widget  to  provide  a  text  entry  widget  but  to 
give  it  no  initial  text 

Implementing  xbox3  requires  five  steps: 

1.  Creating  the  pop-up  shell  widget 

2.  Creating  the  Dialog  widget 

3.  Creating  a  Command  widget  as  a  child  of  the  Dialog  widget  (This  Command  widget  is 
used  to  pop  down  the  dialog  box.) 

4.  Changing  the  callback  function  invoked  by  the  "Press  Me"  button  so  that  it  pops  up  the 
widget 

5.  Writing  the  callback  that  pops  down  the  widget 
Example  3-5  shows  the  code  added  to  xboxl  to  develop  xboxS. 

Example  3-5.  Creating  a  pop-up  dialog  box 


/*  Needed  for  creating  popup  shell  */ 
tinclude  <Xll/Shell .h> 

/* 

*  Public  include  files  for  widgets  used  in  this  file. 
V 

tifdef  X11R3 

tinclude  <Xll/Dialog.h> 

#else       /*  R4  and  later  */ 

tinclude  <Xll/Xaw/Dialog.h> 

#endif      /*  X11R3  */ 

/* 

*  Both  dialog  and  pshell  are  needed  in  the  dialogDone  callback, 

*  and  both  can't  be  passed  in  without  creating  a  structure. 

*  So  we  chose  to  pass  dialog  in,  and  make  pshell  global. 

*  pressme  and  quit  are  needed  in  both  callbacks,  so  they  are 

*  declared  global  as  well. 
*/ 

Widget  pshell,  pressme,  quit; 

/* 

*  dialog  button 
*/ 

void  PopupDialog(w,  topLevel,  call_data) 

Widget  w; 

Widget  topLevel;   /*  client_data  */ 

caddr_t  call_data; 

{ 

Position  x,  y; 

Dimension  width,  height; 

Arg  arg [2] ; 

int  i; 

/* 

*  get  the  coordinates  of  the  middle  of  topLevel  widget. 
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Example  3-5.  Creating  a  pop-up  dialog  box  (continued) 

*/ 

i   =   0; 

XtSetArg(arg[i] ,  XtNwidth,  swidth) ; 
XtSetArg(arg[i] ,  XtNheight,  Sheight) ; 
XtGetValues (topLevel,  arg,  i)  ; 

/* 

*  translate  coordinates  in  application  top-level  window 

*  into  coordinates  from  root  window  origin. 
*/ 

XtTranslateCoords (topLevel,   /*  Widget  */ 
(Position)  width/2,  /*  x  */ 
(Position)  height/2,  /*  y  */ 
&x,  &y)  ;  /*  coords  on  root  window  */ 

/*  move  popup  shell  to  this  position  (it's  not  visible  yet)  */ 

i  =  0; 

XtSetArg(arg[i] ,  XtNx,  x) ; 

XtSetArg(arg[i] ,  XtNy,  y) ; 

XtSetValues (pshell,  arg,  i)  ; 

/* 

*  Indicate  to  user  that  dialog  popup  button 

*  is  invalid  while  dialog  is  already  popped  up... 
*/ 

XtSetSensitive (pressme,  FALSE); 

XtPopup (pshell,  XtGrabNonexclusive) ; 

} 

/* 

*  dialog  done  button 

*/ 

void  DialogDone (w,  dialog,  call_data) 
Widget  w; 

Widget  dialog;     /*  client_data  */ 
caddr_t  call_data; 
{ 

String  string; 

XtPopdown (pshell)  ; 
XtSetSensitive (pressme,  TRUE) ; 

fifdef  X11R3 

string  =  XtDialogGetValueString (dialog) ; 
telse  /*  R4  and  later  */ 

string  =  XawDialogGetValueString (dialog) ; 
tendif  /*  X11R3  */ 

printf ("User  typed:  %s\n",  string); 
} 

main(argc,  argv) 
int  argc; 
char  **argv; 
{ 

Widget  box,  topLevel,  dialog,  dialogDone; 
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Example  3-5.  Creating  a  pop-up  dialog  box  (continued) 

/*  Xtlnitialize,  create  Box  widget,  etc.  */ 

pressme  =  XtCreateManagedWidget ( 

"pressme",  /*  widget  name  */ 

commandWidgetClass,  /*  widget  class  */ 

box,  /*  parent  widget  */ 

NULL,  /*  argument  list  */ 

0  /*  arglist  size  */ 
); 

pshell  =  XtCreatePopupShell ( 
"pshell11, 

transient ShellWidgetClass, 
topLevel, 
NULL, 
0 
); 

dialog  =  XtCreateManagedWidget ( 

"dialog",  /*  widget  name  */ 

dialogWidgetClass,  /*  widget  class  */ 

pshell,  /*  parent  widget  */ 

NULL,  /*  argument  list  */ 

0  /*  arglist  size  */ 
); 

dialogDone  =  XtCreateManagedWidget ( 

"dialogDone",  /*  widget  name  */ 

commandWidgetClass,  /*  widget  class  */ 

dialog,  /*  parent  widget  */ 

NULL,  /*  argument  list  */ 

0  /*  arglist  size  */ 
); 

XtAddCallback (quit,  XtNcallback,  Quit,  0)  ; 

XtAddCallback {dialogDone,  XtNcallback,  DialogDone,  dialog); 
XtAddCallback {pressme,  XtNcallback,  PopupDialog,  topLevel); 
XtRealizeWidget (topLevel) ; 

XtMainLoopO  ; 

} 

The  pop-up  shell  widget  is  created  by  a  call  to  XtCreatePopupShell  rather  than  Xt 
CreateManagedWidget.  The  widget  class  is  specified  as  transientShell- 
WidgetClass  for  dialog  boxes,  and  overrideShellWidgetClass  for  menus. 

Note  that  you  must  include  <X1  II Shell. h>  to  create  a  TransientShell  or  OverrideShell  widget. 
The  Shell  class  actually  has  several  subclasses,  each  with  slightly  different  characteristics. 
For  convenience,  all  of  Shell's  subclasses  use  the  same  include  file.  The  other  subclasses  of 
Shell  are  less  frequently  used  than  the  top  level  shell  returned  by  Xtlnitialize  and  the 
TransientShell  used  for  pop  ups  and  are  described  in  Section  13.7. 

It  is  often  helpful  for  some  or  all  of  the  widget  IDs  involved  in  pop  ups  to  be  global  variables 
in  the  application.  As  we  will  see  in  the  discussion  of  passing  data  to  callback  functions,  it  is 
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awkward  to  pass  more  than  one  piece  of  data  into  any  one  callback  function  (one  has  to  cre 
ate  a  structure  containing  them  and  pass  the  pointer  to  the  structure).  When  two  or  more 
widget  IDs  are  used  in  any  callback,  it  is  simplest  to  declare  one  or  more  of  them  global.  In 
Example  3-5,  pshell,  pressme,  and  quit  are  declared  global. 

The  Dialog  widget  is  a  compound  widget — it  creates  its  own  widget  children  in  addition  to 
letting  the  application  add  children.  Its  purpose  is  to  make  it  easier  to  combine  existing 
widgets  in  a  standard,  useful  way.  It  is  really  a  subclass  of  the  Form  widget,  to  which  a  Label 
widget  child  is  added  to  tell  the  user  the  purpose  of  the  box  and,  with  certain  resource  values, 
an  Athena  Text  widget  child  is  added  for  text  entry.  Ideally,  the  Text  widget  should  provide  a 
callback  (which  could  be  used  to  provide  the  data  the  user  entered  and  popdown  the  dialog 
box)  when  the  user  types  the  Return  key.  Many  applications  add  this  missing  feature  by 
overriding  the  translation  for  the  Return  key  in  the  Text  widget,  or  by  displaying  a  Command 
button  to  provide  the  callback. 

The  Label  widget  and  Text  widget  are  automatically  created  as  part  of  the  Dialog  widget. 
However,  you  have  to  explicitly  create  the  Command  widget  as  a  child  of  the  Dialog  widget. 
The  Dialog  widget  does  automatically  set  the  constraint  resources  that  Form  uses  to  place 
and  size  the  Command  widget  The  callback  function  called  by  this  Command  widget  is 
called  DialogDone. 

The  pressme  Command  widget's  callback  function  is  called  PopupDialog.  Most  of  its 
code  places  the  pop-up  widget,  because  pop  ups  appear  at  the  top  left  corner  of  the  screen  by 
default.  This  example  centers  the  corner  of  the  pop  up  in  the  top  level  widget  of  the  applica 
tion.  Since  pop  up  coordinates  are  relative  to  the  corner  of  the  root  window,  centering  is  a 
three-step  process: 

1.  Get  the  width  and  height  of  top-level  window  with  xt  Get  Values. 

2.  Translate  the  center  point  into  root  window  coordinates  with  xtTranslateCoords. 

3.  Move  the  pop-up  shell  there  by  setting  the  xtNx  and  XtNy  resources  with  xtSet- 
Values. 

When  you  pop  up  a  widget  from  an  action  instead  of  a  callback,  you  can  use  the  content  of 
the  event  to  place  the  pop  up  and  avoid  the  last  two  steps. 

Pop-up  windows  appear  at  the  corner  of  the  screen  by  default  because  their  windows  are  chil 
dren  of  the  root  window,  not  children  of  the  top-level  window  of  the  application.  This  allows 
the  pop  up  to  extend  beyond  the  border  of  the  application,  as  was  shown  in  Figure  3-5. 
Pop-up  windows  are  the  only  difference  between  the  widget  hierarchy  created  by  an  applicaT 
tion  and  its  X  window  hierarchy.  Figure  3-7  shows  the  two  hierarchies  forxbox3. 

The  PopupDialog  callback  function  sets  the  Command  widgets  in  the  application  to 
insensitive  mode  with  xtSetSensitive*  just  before  it  pops  up  the  dialog  box.  This  is 
done  to  indicate  to  the  user  that  the  data  asked  for  in  the  callback  function  must  be  provided 
before  executing  any  other  application  command.  When  the  data  is  furnished,  the  applica 
tion  must  turn  sensitivity  back  on  again. 


"This  could  also  be  done  by  setting  the  widgets'  XtNsensitive  resource  with  XtSetValues.  Calling  Xt 
SetSensitive  is  slightly  faster. 
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Instance  hierarchy 
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Figure  3-7.  The  widget  instance  and  X  window  hierarchies  are  different  only  for  pop  ups 

The  DialogDone  callback  function  pops  down  the  pop-up  shell,  sets  the  application's 
Command  widget  back  to  sensitive  mode,  gets  the  value  the  user  typed,  and  prints  it 

If  you  have  a  pop-up  widget  that  might  never  be  used,  or  whose  characteristics  are  not  known 
until  just  before  it  is  popped  up,  you  can  create  the  pop-up  shell  and  widget  just  before  pop 
ping  it  up,  in  the  callback  function  or  action  that  pops  up  the  widget  This  makes  the  startup 
time  of  the  application  marginally  faster,  but  slows  the  pop-up  time  the  first  time  the  pop  up 
is  used. 

Pop  ups,  and  menus  in  particular,  will  be  described  in  much  more  detail  in  Chapter  12, 
Menus,  Gadgets,  and  Cascaded  Pop  Ups. 
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3.4  More  About  Callbacks 

As  you  may  recall,  a  callback  is  a  function  that  your  application  wants  called  in  response  to  a 
specified  occurrence  in  a  certain  widget.  The  application  simply  declares  the  callback  func 
tion  and  then  calls  XtAddCallback.  While  Chapter  2Jntroduction  to  the  X  Toolkit,  dis 
cussed  the  concept  of  callbacks  and  demonstrated  the  most  common  use,  it  did  not  com 
pletely  describe  all  the  useful  tricks.  You  can  pass  application  data  to  callback  functions. 
You  can  arrange  for  more  than  one  callback  function  to  be  called  (in  a  particular  order)  when 
the  callback  is  triggered,  and  add  and  remove  functions  from  this  list  at  will.  You  can  declare 
callbacks  statically  using  a  callback  list  instead  of  calling  XtAddCallback. 


Passing  Data  to  Callback  Functions 

A  callback  function  is  called  with  three  arguments:  widget,  client_data,  and 
call_data. 

The  application  determines  the  use  of  the  client_data  argument,  while  the  widget  deter 
mines  the  use  of  the  call_data  argument  As  described  earlier,  the  widget  argument  is 
necessary  if  you  have  registered  the  same  callback  function  for  two  widgets,  and  you  need  to 
know  which  widget  called  the  function.  It  also  may  be  used  in  routine  ways,  such  as  for  the 
argument  of  macros.  The  call_data  argument  is  passed  in  from  the  widget  itself.  This 
argument's  value  is  defined  by  the  widget,  and  is  described  in  the  documentation  for  the 
widget  unless  it  is  not  used.  Few  of  the  Athena  Widgets  use  the  call_data  argument,  but 
other  widgets  do  use  it  occasionally. 

You  may  pass  a  single  piece  of  data  as  the  clien  t_da  ta  argument,  or  a  pointer  to  a  struc 
ture  containing  several  pieces  of  data.  You  may  ask,  "Why  bother  with  passing  data  to  a  call 
back  when  I  can  just  declare  a  global  variable?"  For  one  thing,  it  is  a  general  principle  of 
good  C  coding  to  use  a  global  variable  only  where  the  variable  is  needed  in  several  functions 
and  the  arguments  would  otherwise  prove  unwieldy.  Secondly,  using  the  client_data 
argument  makes  clear  the  purpose  of  your  variable,  whereas  it  is  difficult  to  trace  where  a 
global  variable  is  set  or  referenced.  However,  if  you  find  it  necessary  to  change  the 
client_data  argument  in  a  number  of  functions  in  the  application,  you  will  need  a  global 
variable  anyway,  and  there  is  nothing  that  says  you  must  use  client_data  (but  be  sure  to 
document  what  you  are  doing!). 

Example  3-6  demonstrates  how  to  pass  a  single  piece  of  data  into  a  callback  function. 
Example  3-6.  Passing  a  single  value  to  a  callback  function 

/*ARGSUSED*/ 

void  PressMe(w,  client_data,  call_data) 

Widget  w; 

caddr_t  client_data,  call_data; 

{ 

fprintf (stderr,  "%s\n",  client_data) ; 

} 

main(argc,  argv) 
int  argc; 
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Example  3-6.  Passing  a  single  value  to  a  callback  function  (continued) 
char    **argv; 

Widget  pressme; 

/*  Xtlnitialize,  create  pressme  widget  */ 

4 

/*  last  argument  is  client_data  */ 

XtAddCallback (pressme,  XtNcallback,  PressMe,  "Thanks") 


Example  3-7  demonstrates  passing  a  pointer  to  a  structure  into  a  callback  function. 

Example  3-7.  Passing  a  pointer  to  a  structure  to  a  callback  function 

typedef  struct  { 

String  name; 

String  street; 

String  city; 
}  app_stuff; 

/*ARGSUSEDV 

void  PressMe (w,  address,  call_data) 

Widget  w; 

app_stuff  *address; 

caddr_t  call_data; 

{ 

/* 

*  Alternately,  the  second  argument  can  remain  declared  as 

*  client_data,  and  the  following  cast  can  be  used: 

app_stuff  *address  =  (app_stuff  *)  client_data; 
*/ 

fprintf (stderr,  "%s\n%s\n%s\n",  address->name,  address->street, 
address->city) ; 

} 

main(argc,  argv) 
int  argc; 
char  **argv; 
{ 

Widget  box,  quit,  pressme,  topLevel; 

static  app_stuff  stuff  =  { 
"John  Doe", 

"1776  Constitution  Way", 
"Philadelphia,  PA  01029" 


/*  Xtlnitialize,  create  pressme  widget  */ 
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Examples-?.  Passing  a  pointer  to  a  structure  to  a  callback  function  (continued) 

XtAddCallback(pressme,  XtNcallback,  PressMe,  &stuf  f  )  ; 


3.4.2   Callback  Lists 

You  may  register  any  number  of  callback  functions  for  a  single  widget  callback  resource.  In 
other  words,  when  a  callback  is  triggered  by  a  user  event,  all  the  functions  in  the  current  call 
back  list  for  that  callback  for  that  widget  instance  will  be  called,  one  at  a  time,  in  the  speci 
fied  order.  Multiple  callback  functions  are  not  needed  in  many  applications,  but  can  be  use 
ful  if  applied  creatively. 

Remember  that  a  widget  may  also  have  more  than  one  callback  list,  each  triggered  by  a  dif 
ferent  occurrence.  For  example,  the  Command  widget  has  XtNcallback,  which  is  trig 
gered  by  a  pointer  button  click,  and  xtNdestroyCallback,  which  is  triggered  when  the 
widget  is  destroyed.  Each  of  these  callback  resources  exists  as  a  separate  callback  list  for 
every  instance  of  the  widget. 

Xt  supplies  three  standard  callback  functions  that  pop  up  a  widget  xtCallbackNone, 
XtCallbackExclusive,  and  XtCallbackNonexclusive.* 

Do  not  be  confused  by  the  names  of  the  standard  pop-up  callback  functions.  Even  though 
their  names  do  not  include  the  word  Popup,  their  only  use  is  to  pop-up  widgets. 

Each  of  these  functions  pops  up  the  widget  specified  in  the  client_data  argument.  Xt 
CallbackExclusive  and  XtCallbackNonexclusive  also  grab  certain  events  so 
that  the  user  must  provide  the  information  requested  before  continuing.  Exclusive  is  for 
use  when  you  create  a  single  pop  up  such  as  a  menu  or  dialog  box,  and  Nonexclusive  is 
for  when  you  pop  up  a  menu  that  pops  up  submenus.  Since  these  standard  pop-up  callback 
functions  do  not  move  the  pop-up  widget  before  popping  it  up,  it  is  a  good  idea  to  add 
another  callback  function  to  the  callback  list  before  them,  to  place  the  widget.  xboxS,  which 
is  not  shown  in  this  book  but  is  included  in  the  example  source,  creates  a  callback  list  com 
posed  of  PrepareDialog  (which  moves  the  pop  up  to  the  proper  location)  and  Xt 
CallbackExclusive. 

Let's  take  another  example  of  how  a  callback  list  might  be  used.  Perhaps  you  have  the  func 
tions  A,  B,  and  C,  and  you  need  to  be  able  to  call  them  separately  in  response  to  events  in 
three  different  Command  widgets,  or  to  call  all  of  them  in  order  in  response  to  events  in  a 
fourth  Command  widget  This  fourth  Command  widget  might  have  a  callback  list  including 
the  functions  A,  B,  and  C.  While  this  can  also  be  implemented  by  creating  a  function  D  that 
calls  A,  B,  and  C  and  then  registering  D  as  the  callback  of  the  fourth  Command  widget,  you 
can't  pass  a  different  piece  of  data  into  each  routine,  and  you  can't  change  the  order  of  the 
functions  called  by  D.  You  can  do  both  easily  if  A,  B,  and  C  are  specified  in  a  callback  list. 


"These  standard  callback  functions  also  set  the  calling  widget  (usually  a  Command  widget)  to  insensitive  mode.  You 
must  set  the  parent  widget  back  to  sensitive  mode  when  you  pop  down  the  widget 
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The  order  in  which  the  callback  functions  are  called  can  be  changed  by  removing  them  from 
the  list  (using  XtRemoveCallback,  XtRemoveCallbacks,  or  XtRemoveAll- 
Callbacks)  and  then  adding  them  in  a  different  order.  You  can  also  call  the  same  function 
more  than  once  in  a  callback  list. 

One  way  to  add  more  than  one  callback  function  is  to  call  XtAddCallback  more  than 
once.  Another  way  is  to  call  XtAddCallbacks,  which  takes  an  XtCallbackRec  array 
as  an  argument.  This  array  is  usually  initialized  at  compile  time,  as  shown  in  Example  3-8. 
The  final  NULL,  NULL  entry  terminates  the  list.  (This  particular  list  registers  the  functions 
do_A  and  then_B,  and  passes  them  both  0  as  client_data.) 

Example  3-8.  Initializing  a  callback  list 

XtCallbackRec  quit_callback_list [ ] = { 

{do_A,  0}, 

{then_B,  0}, 

{ (XtCallbackProc)    NULL,     (caddr_t)    NULL} 
}; 

This  form  of  XtCallbackRec  list  can  also  be  used  to  replace  a  callback  list  with  xt  Set- 
Values  (but  not  to  get  a  callback  list,  because  Xt  compiles  the  list  into  an  internal  form). 
As  demonstrated  in  Section  3.7.1,  an  XtCallbackRec  list  can  also  be  used  to  register  one 
or  more  callbacks  when  creating  a  widget. 


3.5  Application  Resources 

You  already  know  that  widgets  declare  resources  that  can  be  configured  through  the  resource 
mechanism.  In  addition,  the  application  itself  may  have  variables  that  it  wants  the  user  to  be 
able  to  configure  from  the  resource  databases,  even  though  these  variables  have  nothing  to  do 
with  widgets.  These  are  called  application  resources. 

Application  resources  are  just  like  widget  resources  except  that  they  apply  to  application 
code,  not  to  the  widgets  it  creates. 

There  are  three  steps  for  adding  application  resources.  You  must: 

1.  Create  an  application  data  structure  containing  the  variables  to  be  set  via  the  resource 
mechanism. 

2.  Create  a  resource  table  defining  the  type  and  default  value  for  each  variable. 

3.  Call  xtGetApplicationResources  with  pointers  to  the  application  data  structure 
and  resource  table  as  arguments.  When  this  function  returns,  the  application  data  struc 
ture  will  contain  the  current  settings  from  the  resource  databases. 

To  demonstrate  how  to  get  application  resources,  we  will  jump  ahead  and  describe  a  portion 
of  the  code  for  the  xbitmap4  bitmap  editor  example  described  in  Chapter  4,  An  Example 
Application.  Since  this  application  draws  into  a  widget  using  Xlib,  it  needs  two  colors  to 
draw  with.  The  bitmap  editor  also  allows  the  user  to  specify  the  dimensions  of  the  bitmap  in 
cells,  and  the  size  of  each  cell  in  pixels.  And,  for  general  utility,  it  includes  a  debug  flag  that 
can  be  set  in  the  application  to  invoke  or  ignore  debugging  code  without  recompiling. 
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3.5.1  The  Application  Data  Structure 

The  structure  type  that  contains  all  the  application  variables  to  be  set  through  resources  is 
commonly  called  AppData.  Once  this  structure  type  is  declared,  memory  can  be  allocated 
for  a  structure  called  app_data.  Example  3-9  shows  the  code  that  defines  the  structure 
type  and  then  allocates  memory  for  the  actual  structure. 

Example  3-9.  xbitmap:  getting  application  resources 

typedef  struct  { 

Pixel  copy_fg; 

Pixel  copy_bg; 

int  pixmap_width_in_cells; 

int  pixmap_height_in_cells; 

int  cell_size_in_pixels; 

Boolean  debug; 
}  AppData,  *AppDataPtr; 

AppData  app_data; 

Note  that  a  pointer  called  AppDataPtr  is  defined  for  convenience  in  defining  the  resource 
list  (as  described  in  a  moment). 

As  usual  in  C,  the  members  of  the  app_data  structure  will  be  referenced  throughout  the 
application  code  using  the  dot  format.  For  example,  the  value  of  the  debug  field  of 
app_data  will  be  referenced  with  app_data .  debug. 

3.5.2  The  Resource  List 

The  resource  list  looks  complicated,  but  it  is  easy  to  understand  and  even  easier  to  write 
because  it  conforms  to  a  consistent  pattern.  Each  field  in  the  application  data  structure  has  an 
entry  in  the  resource  list.  Each  resource  user  entry  in  turn  has  seven  fields,  which  describe 
the  name  of  the  resource,  its  type  and  default  value,  and  various  other  information. 

The  resource  list  controls  Xt's  value  conversion  facilities.  Since  user  resources  are  always 
strings,  and  application  data  structure  fields  can  be  any  type,  a  conversion  may  have  to  take 
place.  Xt  has  built-in  converters  to  convert  from  string  to  most  common  types  needed  by 
applications.  These  types  are  called  representation  types  by  Xt,  and  they  are  indicated  by 
constants  starting  with  xtR.  The  representation  type  of  a  string  is  xtRString.  You  con 
trol  the  conversion  simply  by  specifying  a  resource  as  a  certain  representation  type  in  the 
resource  list. 

Note  that  a  representation  type  is  different  from  a  C-language  type.  For  example,  a  color 
may  be  represented  as  an  ASCII  color  name  such  as  "blue,"  as  a  structure  containing  Red, 
Green,  and  Blue  values,  or  as  a  pixel  value  (an  index  into  a  colormap.)  It  is  also  possible  for 
two  different  representations  of  something  to  both  use  the  same  C-language  type.  For 
example,  two  hypothetical  representation  types  might  be  xtRlnch  and  xtRMeter.  Both 
represent  distances  and  both  would  probably  be  floating  point  numbers,  but  each  would  have 
a  different  value  for  the  same  distance. 
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See  Chapter  9,  Resource  Management  and  Type  Conversion,  for  a  description  of  the  standard 
representation  types,  as  well  as  information  on  how  to  write  your  own  converter  routine. 

Example  3-10  shows  the  resource  list  for  xbitmap,  followed  by  a  description  of  each  of  the 
fields  in  each  entry. 

Example  3- 1 0.  The  resource  list  for  xbitmap 

/* 
*  The  following  could  be  placed  in  a  "xbitmap. hn  file. 

*/ 

fdefine  XtNdebug  "debug" 
#define  XtCDebug  "Debug" 

#define  XtNpixmapWidthlnCells  "pixmapWidthlnCells" 
tdefine  XtCPixmapWidthlnCells  "PixmapWidthlnCells" 
tdefine  XtNpixmapHeightlnCells  "pixmapHeightlnCells" 
tdefine  XtCPixmapHeightlnCells  "PixmapHeightlnCells" 
tdefine  XtNcellSizelnPixels  "cellSizelnPixels" 
#define  XtCCellSizelnPixels  "CellSizelnPixels" 

static  XtResource  resources!]  =  { 
{ 

XtNforeground, 

XtCForeground, 

XtRPixel, 

sizeof (Pixel) , 

XtOf f set (AppDataPtr,  copy_fg) , 

XtRString, 

XtDefaultForeground 
}, 
{ 

XtNbackground, 

XtCBackground, 

XtRPixel, 

sizeof (Pixel) , 

XtOf f set (AppDataPtr,  copy_bg) , 

XtRString, 

XtDefaultBackground 
>, 
{ 

XtNpixmapWidthlnCells, 

XtCPixmapWidthlnCells, 

XtRInt, 

sizeof (int) , 

XtOf f set (AppDataPtr,  pixmap_width_in_cells) , 

XtRImmediate, 
(caddr_t)  32, 
}, 
{ 

XtNpixmapHeightlnCells, 

XtCPixmapHeightlnCells, 

XtRInt, 

sizeof (int) , 

XtOf fset (AppDataPtr,  pixmap_height_in_cells) , 

XtRImmediate, 
(caddr_t)  32, 
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Example  3-10.  The  resource  list  for  xbilmap  (continued) 

XtNcellSizelnPixels, 

XtCCellSizelnPixels, 

XtRInt, 

sizeof (int) , 

XtOf f set (AppDataPtr,  cell_size_in_pixels) , 

XtRImmediate, 

(caddr  t)  30, 


XtNdebug, 
XtCDebug, 
XtRBoolean, 
sizeof (Boolean) , 
XtOf f set (AppDataPtr,  debug) , 
XtRImmediate, 
(caddr_t)  FALSE, 
>, 

}; 

A  resource  list  entry  has  the  following  fields: 

•  The  first  two  fields  of  each  entry  are  the  name  and  class  of  the  resource,  both  strings. 
These  are  specified  as  symbolic  constants  to  improve  compile-time  checking,  and  should 
be  selected  from  <Xll/StringDefs.h>  if  any  there  have  an  appropriate  name,  or  they  can 
be  defined  in  your  application's  own  include  file.   For  the  debug  resource  entry,  the 
resource  name  and  class  strings  would  be  "debug"  and  "Debug,"  respectively  defined  in 
the  application's  include  file  as  XtNdebug  and  XtCDebug. 

•  The  third  field  is  the  representation  type.  A  representation  type  is  a  symbolic  constant, 
beginning  with  xtR,  that  defines  the  data  type  of  a  resource.  Because  user  resource  spec 
ifications  are  always  in  the  form  of  strings,  but  the  actual  resources  may  be  of  any  type, 
Xt  uses  resource  converters  to  convert  the  string  representation  to  the  actual  target  type. 
If  necessary,  you  can  define  your  own  representation  type  in  your  application  include  file, 
but  you  will  also  have  to  provide  Xt  with  a  way  to  convert  from  string  to  this  type  with  a 
type  converter  function,  as  described  in  Chapter  9,  Resource  Management  and  Type  Con 
version.  Table  3-1  lists  the  correspondence  between  the  representation  types  defined  in 
<Xll/StringDefs.h>  and  actual  C  data  types  or  X  data  types  and  structures. 

•  The  fourth  field,  the  size  of  the  representation,  is  specified  using  the  C  macro  sizeof 
with  the  actual  C  type  as  an  argument  For  example,  when  the  representation  type  is  Xt 
RBoolean,  the  size  field  is  sizeof  (Boolean) . 

•  The  fifth  field  identifies  the  place  in  your  application's  data  structure  where  Xt  is  to  place 
the  converted  value.  In  Example  3-11,  the  structure  is  called  AppData,  and  the  pointer 
to  it  is  called  AppDataPtr.  This  field  for  the  debug  resource  entry  is  specified  using 
the  XtOffset  macro  as  xtOff set  (AppDataPtr,     debug).   Note  that  the  field 
name  in  the  application  data  structure  is  often  the  same  as  the  resource  name,  except  with 
all  word-transitions  marked  with  an  underscore  instead  of  a  capital  letter. 

•  The  sixth  field  specifies  the  representation  type  of  the  default  value  (the  seventh  field). 
Xt  has  routines  for  converting  data  between  types.  They  are  used  to  translate  strings  from 
the  resource  databases  into  certain  representation  types.  Therefore,  you  can  specify  the 
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default  value  as  a  string  (among  other  things)  and  Xt  will  convert  it  to  the  representation 
type  you  specified  in  field  three,  if  the  default  value  is  needed.  If  the  representation  type 
in  field  three  is  not  standard  in  Xt,  you  will  have  to  write  the  conversion  routine  that  con 
verts  from  XtRSt  ring  to  that  representation,  as  described  in  Chapter  9,  Resource  Man 
agement  and  Type  Conversion.  In  Release  3  and  later,  you  can  also  use  the  special  con 
stant  xtRlmmediate  here,  which  indicates  that  the  value  in  field  seven  can  be  used 
without  conversion.  Using  XtRlmmediate  should  lead  to  faster  startup. 

The  seventh  field  is  the  default  value,  using  the  representation  type  specified  in  field  six. 
This  default  value  will  be  set  into  the  application  data  structure  field  if  there  is  no  setting 
for  this  resource  in  the  resource  database. 


Table  3-1.  Resource  type  strings 


Resource  Type 


Data  Type 


XtRAcceleratorTable 

XtRBoolean 

XtRBool 

XtRCallback 

XtRColor 

XtRCursor 

XtRDimension 

XtRDisplay 

XtRFile 

XtRFloat 

XtRFont 

XtRFontStruct 

XtRFunction 

XtRInt 

XtRPixel 

XtRPixmap 

XtRPointer 

XtRPosition 

XtRShort 

XtRString 

XtRTranslationTable 

XtRUnsignedChar 

XtRWidget 

XtRWindow 


Xt Accelerators 

Boolean 

Bool 

XtCallbackList 

XColor 

Cursor 

Dimension 

Display* 

FILE* 

float 

Font 

XFontStruct  * 

(*)  () 

int 

Pixel 

Pixmap 

caddr_t 

Position 

short 

char* 

XtTranslations 

unsigned  char 

Widget 

Window 
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3.5.3   Getting  the  Resources 

Once  the  application  data  structure  and  resource  list  are  set  up,  you  pass  pointers  to  them  to 
XtGetApplicationResources,  just  after  calling  Xtlnitialize.  XtGet- 
ApplicationResources  will  search  the  databases  for  any  matching  resource  settings 
and  set  the  fields  in  the  application  data  structure. 

The  last  requirement  is  that  you  check  the  values  specified  by  the  user  to  make  sure  they  are 
acceptable.  Example  3-11  shows  these  two  steps  from  xbitmap4. 

Example  3-11.  Calling  XtGetApplicationResources  and  checking  values 


AppData   app_data; 


main(argc,  argv) 
int  argc; 
char  *argv[ ] ; 

{ 

Widget  toplevel,  vpane,  buttonbox,  quit,  output; 


/*  call  Xtlnitialize  here  */ 

XtGetApplicationResources (toplevel, 
&app_data, 
resources, 

XtNumber (resources)  , 

NULL,     /*  argument  list  and  length  for  making  */ 
0)  ;       /*  application  resources  non-user-configurable  */ 

/* 

*  We  must  check  the  application  resource  values  here. 

*  Otherwise,  user  could  supply  out  of  range  values. 

*  Conversion  routines  do  this  automatically,  so 

*  colors  are  already  checked. 

*/ 

if  ( (app_data.pixmap_width_in_cells  >  MAXBITMAPWIDTH)  || 
(app_data.pixmap_width_in_cells  <  MINBITMAPWIDTH)  I  I 
(app_data.pixmap_height_in_cells  >  MAXBITMAPWIDTH)  | | 
(app_data.pixmap_height_in_cells  <  MINBITMAPWIDTH))  { 
fprintf (stderr,  "xbitmap:  error  in  resource  settings:", 

"bitmap  dimension  must  be  between  %d  and  %d  cells\n", 
MINBITMAPWIDTH,  MAXBITMAPWIDTH) ; 
exit(l) ; 

} 

if  ( (app_data.cell_size_in_pixels  <  MINCELLSIZE)  I  I 

(app_data.cell_size_in_pixels  >  MAXCELLSIZE) )  { 
fprintf (stderr,  "xbitmap:  error  in  resource  settings:", 
"cell  size  must  be  between  %d  and  %d  pixels\n", 
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Example  3-11.  Calling  XtGetApplicationResources  and  checking  values  (continued) 

MINCELLSIZE,  MAXCELLSIZE)  ; 
exit  (1)  ; 


Note  that  only  certain  of  the  application  resources  need  their  values  checked.  Because  Xt 
automatically  converts  the  user's  color  specifications  (such  as  "blue")  into  the  form  required 
by  X,  it  takes  care  of  warning  the  user  when  a  color  is  specified  improperly.*  In  this  case, 
only  the  bitmap  dimensions  and  cell  size  are  checked,  since  they  are  critical  to  the  applica 
tion's  operation. 


3.6  Command-line  Options 

You  already  know  that  Xt  automatically  customizes  widgets  according  to  the  resource  data 
base,  but  this  is  not  the  whole  story.  Users  often  expect  command-line  arguments  for  the 
most  important  aspects  of  an  application.  By  default,  Xt  Initialize  understands  only  a 
minimal  set  of  command-line  arguments;  more  need  to  be  added  so  that  application  resources 
and  certain  widget  resources  can  be  set  from  the  command  line. 

There  is  no  point,  however,  in  trying  to  make  every  widget  resource  sellable  from  ihe  com 
mand  line,  because  that's  the  purpose  of  the  resource  database.  You  should  concentrate  on 
the  resources  that  the  user  is  most  likely  to  want  to  have  different  between  two  simultaneous 
instances  of  the  application  (since  it  is  difficult  to  arrange  this  with  the  resource  database). 

Before  describing  how  to  define  your  own  command-line  arguments,  we  need  to  describe 
what  command-line  arguments  Xt  Initialize  already  handles. 

3.6.1    Standard  Command-line  Options 

First  of  all,  Xt  Initialize  recognizes  the  -xrm  option  for  setting  any  widget  or  applica 
tion  resource.  For  example: 

spike%   xhallo   -xrm  ' * background:    blue' 

This  option  is  a  little  awkward.  Not  only  is  it  long,  but  csh  users  must  quote  the  string  with 
right-handed  single  quotes  so  that  the  *  is  not  interpreted  by  the  shell. 


*That  is,  if  the  resource  in  a  database  file  is  specified  properly,  but  the  value  is  not,  Xt  will  warn  the  user.  However,  if 
the  resource  is  not  specified  properly,  Xt  has  no  way  of  knowing  that  the  resource  was  intended  to  specify  a  color, 
and  therefore,  no  message  will  be  issued.  For  example,  "* background:  grein"  will  elicit  a  warning  message  because 
green  is  misspelled,  but  "*backgruond:  green"  will  not,  because  the  resource  identifier  is  misspelled. 
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Xt Initialize  also  understands  some  command-line  options  that  were  considered  so 
basic  that  they  should  be  the  same  for  all  applications.  The  above  -xrm  command  line  can  be 
replaced  by: 


spike%   achallo    -background  blu« 


or 


spike%    xhallo   -bg  blua 

Xt  Initialize  also  understands  any  unique  abbreviation  of  an  option  name,  such  as: 

spike %  xhallo  -backg  blue 

These  resources  will  work  with  any  application  written  using  the  X  Toolkit — with  any  widget 
set  Try  the  command  line  above  if  you  have  a  color  screen.  If  not,  try  specifying  a  different 
font,  using  the  -fn  or  -font  option. 

Table  3-2  lists  the  complete  set  of  standard  options.*  Options  for  which  the  resource  name  is 
shown  starting  with  a  dot  rather  than  an  asterisk  set  that  resource  only  in  the  application's 
top-level  Shell. 

Table  3-2.  Standard  command-line  parameters 


Option 

Resource 

Value 

Sets 

-bg 

*background 

next  argument 

background  color 

-background 

*background 

next  argument 

background  color 

-bd 

*borderColor 

next  argument 

border  color 

-bw 

.borderWidth 

next  argument 

width  of  border  in  pixels 

-borderwidth 

.borderWidth 

next  argument 

width  of  border  in  pixels 

-bordercolor 

*border  Color 

next  argument 

color  of  border 

-display 

.display 

next  argument 

server  to  use 

-fg 

*  foreground 

next  argument 

foreground  color 

-fn 

*font 

next  argument 

font  name 

-font 

*font 

next  argument 

font  name 

-foreground 

*f  oreground 

next  argument 

foreground  color 

-geometry 

.geometry 

next  argument 

size  and  position 

-iconic 

.  iconic 

"on" 

start  as  an  icon 

-name 

.name 

next  argument 

name  of  application 

-reverse 

*reverseVideo 

"on" 

reverse  video 

-rv 

*reverseVideo 

"on" 

reverse  video 

+rv 

*reverseVideo 

"off" 

No  Reverse  Video 

-selectionTimeout 

.  selectionTimeout 

Null 

selection  timeout 

-synchronous 

.  synchronous 

"on" 

synchronous  debug  mode 

*There  is  no  legitimate  way  for  the  application  to  access  this  parse  table,  which  is  necessary  to  show  the  user  an  error 
in  a  parameter.  Furthermore,  this  table  is  in  the  source  for  Xt  and  therefore  not  available  online  to  some  Toolkit 
users.  However,  this  parse  table  is  not  expected  to  change  radically  in  new  releases.  Therefore  it  can  probably  be 
safely  copied  from  this  document  into  application  code  to  provide  a  synopsis  of  valid  options.  Most  current  applica 
tions  simply  say  "This  application  understands  all  standard  X  Toolkit  command-line  options." 


More  Widget  Programming  Techniques 


87 


Table  3-2.  Standard  command-line  parameters  (continued) 


Option 

Resource 

Value 

Sets 

asynchronous 
-title 
-xrm 

.  synchronous 
.title 
value  of  argument 

"off' 
next  argument 
next  argument 

synchronous  debug  mode 
tide  of  application 
depends  on  argument 

Note  that  many  of  these  command-line  options  set  the  resource  of  every  widget  in  the  appli 
cation  to  the  same  value.  A  few  of  them  set  the  resources  only  of  the  application's  top-level 
shell  widget 


3.6.2    Defining  Your  Own  Command-line  Options 


Supplying  your  own  command-line  options  allows  you  to  simplify  the  customization  of  your 
application.  It  also  allows  the  user  to  customize  things  that  are  difficult  with  the  resource 
database  (such  as  setting  different  values  for  the  same  resource  in  two  instances  of  the  appli 
cation). 


You  make  xt initialize  understand  additional  command-line  options  by  initializing  a 
XrmOptionDescRec  structure  (called  the  options  table)  and  passing  it  as  an  argument  to 
xt  Initialize.  Example  3-12  shows  the  code  that  implements  command-line  options  for 
the  application  resources  added  in  Examples  3-9, 3-10,  and  3-11. 


Example  3-1 2.  xbitmap:  specifying  command-line  options 

/*  include  files,  etc.  */ 


static  XrmOptionDescRec  options []  =  { 

{"-pw",  "*pixmapWidthInCells", 

{ "-pixmapwidth",   "*pixmapWidthInCells", 


{"-ph", 

{ "-pixmapheighf 

{"-cellsize", 

{"-fg", 

{ "-foreground" , 

{"-debug", 


*pixmapHeight!nCells", 
*pixmapHeight!nCells", 

"*cellSize!nPixels", 

" *  foreground" , 

" *  foreground" , 

"*debug", 


XrmoptionSepArg,  NULL}, 

XrmoptionSepArg,  NULL}, 

XrmoptionSepArg,  NULL}, 

XrmoptionSepArg,  NULL}, 

XrmoptionSepArg,  NULL}, 

XrmoptionSepArg,  NULL}, 

XrmoptionSepArg,  NULL}, 
XrmoptionNoArg,  "True"}, 


static  void  Syntax (argc,  argv) 
int  argc; 
char  *  argv [ ] ; 

int  i; 

static  int  errs  =  False; 

/*  first  argument  is  program  name  -  skip  that  */ 
for  (i  =  1;  i  <  argc;  i++)  { 
if  (!errs++)  /*  do  first  time  through  */ 
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Example  3-1 2.  xbitmap:  specifying  command-line  options  (continued) 


fprintf (stderr,     "xbitmap4 :    command    line   option   unknown :\n") 
fprintf (stderr,    "option:    %s\n",    argv[i]); 


Additional  options  are  as  follows:\nO) ; 


fprintf (stderr,  "xbitmap  understands  all  standard  Xt  \n 
command-line  options . \nO) ; 

fprintf (stderr, 
fprintf (stderr, 
fprintf (stderr, 
fprintf (stderr, 
fprintf (stderr, 
fprintf (stderr, 
fprintf (stderr, 
fprintf (stderr, 
fprintf (stderr, 
fprintf (stderr, 


"Option 

n-pw 

"-pixmapwidth 

»-ph 

"-pixmapheight 

"-cellsize 

"-fg 

"-foreground 

"-debug 


Valid  Range\n") ; 

2  to  1000\n") ; 

2  to  1000\n") ; 

2  to  1000\n") ; 

2  to  1000\n") ; 

4  to  100\n") ; 

color  name\n") ; 

color  name\n") ; 

no  value  necessary\nO) 


main(argc,  argv) 
int  argc; 
char  *argv[] ; 
{ 

Widget  toplevel,  vpane,  buttonbox,  quit,  output; 


toplevel  =  Xtlnitialize  (  argv[0], 
"XBitmap4", 
options, 

XtNumber (options)  , 
Sargc, 
argv) ; 

/*  Xtlnitialize  always  leaves  program  name  in  args  */ 
if  (argc  >  1) 
Syntax (argc,  argv); 


Each  options  table  entry  consists  of  four  fields: 

•  The  option  to  be  searched  for  on  the  command  line.  As  with  standard  command-line 
options,  Xt  will  automatically  accept  any  unique  abbreviation  of  the  option  specified 
here.  For  example,  the  option  -pixmapWidthlnPixels  will  be  recognized  if  typed  on  the 
command  line  as  -pixmapW.  However,  if  you  wanted  the  option  -pw  to  set  the  same 
resource,  then  you  would  need  another  entry,  since  pw  is  not  the  leading  string  of 
pixmapWidthlnPixels. 

•  The  resource  specification.    This  must  identify  a  widget  resource  or  an  application 
resource,  but  not  provide  a  value.  Since  it  has  the  same  form  as  allowed  in  the  resource 
databases,  it  may  apply  to  a  single  widget  or  to  many  widgets.  If  it  applies  to  no  widgets, 
no  error  message  will  be  issued. 


More  Widget  Programming  Techniques 


89 


•  The  argument  style.  This  field  is  one  of  seven  constants  describing  how  the  option  is  to 
be  interpreted.  These  constants  are  described  below  in  Table  3-3. 

•  The  value.  This  field  is  the  value  to  be  used  for  the  resource  if  the  argument  style  is 
XrmOptionNoArg.  This  field  is  not  used  otherwise.  Note  that  this  value  must  already 
be  converted  to  the  value  expected  for  the  resource  (often  not  a  string).  You  may  be  able 
to  use  Xt's  type  converter  routines  explicitly  to  convert  this  data  to  the  right  type  (see 
Section  9.3.5). 

The  enum  constants  that  specify  the  various  command-line  argument  styles  are  as  shown  in 
Table  3-3: 

Table  3-3.  XrmOptbnKind:  Command-line  Option  Style  Constants 


Constant 


Meaning 


XrmoptionNoArg 


XrmoptionlsArg 


XrmoptionStickyArg 

XrmoptionSepArg 
XrmoptionResArg 


Xrmopt  ionSkipAr g 
XrmoptionSkipLine 


Take  the  value  in  the  value  field  of  the  options  table.  For 
example,  this  is  used  for  Boolean  fields,  where  the  option 
might  be  -debug  and  the  default  value  FALSE. 
The  flag  itself  is  the  value  without  any  additional  information. 
For  example,  if  the  option  were  -on,  the  value  would  be  "on." 
This  constant  is  infrequently  used,  because  the  desired  value 
such  as  "on"  is  usually  not  descriptive  enough  when  used  as 
an  option  (-on). 

The  value  is  the  characters  immediately  following  the  option 
with  no  white  space  intervening.  This  is  the  style  of  argu 
ments  for  some  UNIX  utilities  such  as  uucico  where  -sventure 
means  to  call  system  venture. 

The  next  item  after  the  white  space  after  this  flag  is  the  value. 
For  example,  -fg  blue  would  indicate  that  "blue"  is  the  value 
for  the  resource  specified  by  -fg. 

The  resource  name  and  its  value  are  the  next  argument  in 
argv  after  the  white  space  after  this  flag.  For  example,  the 
flag  might  be: 

-res  basecalc*background: white; 

then  the  resource  name/value  pair  would  be  used  as  is.  This 

form  is  rarely  used  because  it  is  equivalent  to  -xrm,  and 

because  the  C  shell  requires  that  special  characters  such  as  * 

be  quoted. 

Ignore  this  option  and  the  next  argument  in  argv. 

Ignore  this  option  and  the  rest  of  argv. 


The  options  table  is  passed  to  xt Initialize  as  its  third  argument,  and  the  number  of 
options  table  entries  as  the  fourth.  The  xt  Number  macro  is  a  convenient  way  to  count  the 
number  of  entries  (this  is  only  one  of  many  contexts  in  which  you'll  see  this  macro  used). 
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Note  that  you  cannot  override  the  standard  options  by  providing  options  with  the  same  names 
in  your  own  parsing  table.  If  you  try  this,  your  options  with  the  same  names  will  simply  not 
be  set  to  the  values  specified  on  the  command  line.  Instead,  the  standard  options  will  be  set 
to  these  values.  This  was  a  design  decision  in  Xt,  one  of  the  few  cases  where  a  user-interface 
policy  is  enforced.  Uniformity  in  this  basic  area  was  deemed  more  valuable  than  flexibility. 

It  is  important  to  check  whether  there  is  more  than  one  argument  left  after  xt  initialize 
has  returned.  Xt  Initialize  conveniently  removes  from  argc  and  argv  the  command- 
line  arguments  that  it  has  already  used  to  set  resources.  Command-line  options  that  xt- 
Initialize  doesn't  recognize  will  be  left  in  argv  and  argc.  This  is  your  chance  to 
catch  this  error  and  tell  the  user.*  The  Syntax  function  shown  in  Example  3-12  demon 
strates  code  that  informs  the  user  of  the  proper  syntax  and  the  option  that  was  not  understood. 
(In  response  to  incorrect  command-line  options,  UNIX  programs  traditionally  print  only  the 
correct  calling  sequence.  However,  you  can  be  even  nicer  to  the  user  by  printing  the  option 
or  options  that  were  in  error,  by  passing  argv  and  argc  into  your  Syntax  function,  as  is 
done  in  Example  3-12. 

Experienced  UNIX  programmers  will  note  that  Xt  applications  can  (but  usually  don't)  use  the 
single-letter  command-line  arguments  mandated  by  POSIX  and  the  System  V  Interface  Defi 
nition.  As  mentioned  earlier,  Xt  automatically  matches  any  unique  abbreviation  for  any  com 
mand-line  option.  For  example,  by  default  the  -display  option  can  be  specified  as  -d,  but  only 
if  you  haven't  included  any  other  option  in  the  options  table  that  also  begins  with  d.  You  can 
define  the  meaning  of  single-letter  options  simply  by  including  them  verbatim  in  the  options 
table.  In  other  words,  if  you  specify  that  -d  turns  on  a  debugging  resource,  Xt  will  no  longer 
try  to  match  any  other,  longer  option  that  also  begins  with  d. 

Note  that  the  argc  and  argv  arguments  of  Xtlnitialize  are  in  the  same  order  as  in 
the  call  to  main.  This  is  the  opposite  order  of  arrays  and  array  lengths  throughout  other  Xt 
and  Xlib  routine  calls.  Also  note  that  the  address  of  argc,  not  argc  itself,  is  passed  to  Xt 
lnitialize.  This  is  so  that  Xtlnitialize  can  decrement  the  count  to  reflect  recog 
nized  options.  Watch  out  for  these  snags. 


3.7  Preventing  User  Customization  of  Widget  Resources 

Although  user  customization  is  good  to  a  certain  degree,  some  resources  need  to  be  hard- 
coded  to  make  sure  that  an  application  will  run  properly  regardless  of  user  configuration. 
This  is  particularly  true  of  widget  geometry  resources  and  constraints.  For  example,  it  is  easy 
to  make  a  mistake  with  Form  widget  constraints  such  that  some  important  widget  is  hidden 
behind  others. 

You  prevent  user  customization  of  particular  resources  by  creating  an  argument  list  and  pass 
ing  it  as  an  argument  to  XtCreateWidget,  or  by  calling  xt  Set  Values  once  the  widget 
already  exists.  The  application  can  still  modify  these  resources  later  using  xtSetvalues. 
Therefore,  this  is  hardcoding  only  from  the  user's  perspective. 


*You  can,  of  course,  intentionally  treat  the  arguments  remaining  after  Xtlnitialize  as  filenames  or  other  pieces 
of  data. 


More  Widget  Programming  Techniques 


The  time  to  hardcode  widget  resources  is  when  development  of  an  application  is  almost  fin 
ished,  because  until  then  the  resource  settings  are  still  in  flux  and  it  is  easier  to  edit  the  appli 
cation-defaults  file  than  it  is  to  recompile  the  application. 

Selecting  which  resources  to  hardcode  is  something  we  can't  help  you  with,  because  there 
isn't  enough  experience  to  go  on  yet.  Some  application  developers  will  hardcode  almost 
everything,  while  others  will  hardcode  nothing.  Only  time  will  tell  where  the  proper  balance 
lies. 


3.7.1    The  Argument  List 

Widget  resources  are  hardcoded  by  creating  an  argument  list  containing  the  resources  to  be 
set  and  their  values,  and  passing  it  to  the  call  to  create  a  widget 

An  argument  list  is  just  an  array  of  Arg  structures,  of  the  same  type  as  you  set  up  to  call  xt  - 
Setvalues  or  xtGetValues.  Once  set,  this  array  is  used  as  an  argument  to  xt- 
CreateManagedWidget.  Each  Arg  structure  contains  a  resource/value  pair.  Attributes 
specified  here  override  the  same  ones  specified  from  the  command  line  or  from  resource  data 
bases. 

Example  3-13  shows  an  argument  list  that  hardcodes  the  sensitivity  of  a  Command  widget 
and  its  callback  list.  The  sensitivity  is  a  good  thing  to  hardcode  for  Command  widgets, 
because  if  set  by  the  user  it  could  disable  an  application.*  The  callback  list  cannot  be  speci 
fied  by  the  user  anyway;  setting  it  here  is  just  an  alternative  to  calling  xtAddCallback. 

The  xtArgVal  type  used  in  the  callback  list  aids  in  porting  Toolkit  programs  to  different 
architectures.  It  allows  the  system  manufacturer  to  select  the  type  in  the  typedef  for  Xt 
ArgVal,  so  that  the  application  program  need  not  worry  about  it.  The  value  field  of  the 
Arg  structure  may  be  a  number  or  a  pointer. 

Example  3-1 3.  An  argument  list 

Arg   quit_args [ ]    =    { 

XtNsensitive,  (XtArgVal)     TRUE, 

XtNcallback,  (XtArgVal)    quit_callback_list, 

}; 

An  argument  list  can  be  used  as  an  argument  in  the  call  to  create  a  widget,  as  shown  in 
Example  3 -14. 

Example  3-14.  Using  an  argument  list  in  widget  creation 

/*  define  quit_args  */ 

main(argc,  argv) 
int  argc; 


^Sensitivity  is  a  basic  resource  of  all  widgets.  When  set  to  TRUE,  the  default,  a  widget  accepts  input  and  operates 
normally.  When  FALSE,  a  widget  displays  itself  in  gray  (or  otherwise  indicates  insensitivity)  and  does  not  act  on 
user  input  The  purpose  of  sensitivity  is  to  allow  the  application  to  disable  certain  commands  when  they  are  not  val 
id.  If  sensitivity  were  left  configurable,  the  user  could  turn  it  off  on  some  widgets  and  effectively  cripple  an  applica 
tion.  It  is  hard  to  imagine  the  user  doing  this  by  accident,  but  it  is  not  worth  taking  a  gamble. 
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Example  3-14.  Using  an  argument  list  in  widget  creation  (continued) 

char  *argv [ ] ; 
{ 

Widget  quit,  box; 

/*  create  box  */ 


quit  =  XtCreateManagedWidget ( 

"quit",  /*  widget  name  */ 

commandWidgetClass,     /*  widget  class  */ 
box,  /*  parent  widget*/ 

quit_args,  /*  argument  list*/ 

XtNumber (quit_args)     /*  arglist  size  */ 


Notice  the  use  of  the  XtNumber  macro  to  calculate  how  many  arguments  there  are  in  the 
statically  initialized  argument  list.  This  macro  eliminates  the  need  to  keep  track  of  the  num 
ber  of  resources  you  have  set 

Note  that  the  value  field  in  the  argument  list  must  be  in  the  correct  representation  type  for 
that  resource,  which  is  often  not  a  string.  You  may  need  to  call  xt  Con  vert  to  arrive  at  the 
right  representation  of  the  data  to  be  placed  in  the  argument  list.  See  Chapter  9,  Resource 
Management  and  Type  Conversion,  for  details  on  calling  xtConvert. 

Unless  you  invoke  a  converter,  no  diagnostic  is  printed  when  you  specify  a  resource  value 
incorrectly  in  the  argument  list.  Therefore,  make  sure  you  specify  these  correctly,  and  recog 
nize  this  as  a  possible  place  to  begin  looking  for  bugs.  (This  is  another  reason  to  hardcode 
resources  only  when  the  application  is  almost  ready  for  release.  If  you  do  it  all  at  once  in  a 
methodical  fashion,  you  are  less  likely  to  make  mistakes  than  if  you  are  always  adding,  sub 
tracting,  and  changing  values  in  the  argument  lists.) 

3.7.1 .1    Another  Way  to  Set  Arguments 

Instead  of  creating  the  argument  list  as  a  static  array,  you  can  allocate  storage  at  run  time  and 
use  the  xtSetArg  macro  to  set  values  into  the  storage.  xtSetArg  sets  a  single  argument 
to  a  resource  identifying  a  constant  and  a  value.  Example  3-15  shows  the  code  that  would 
create  an  argument  list  with  the  same  contents  as  the  one  created  in  Example  3-13  above. 
Some  people  prefer  this  technique  because  it  places  the  argument  list  setting  closer  to  the 
xtCreateWidget  call,  making  the  code  easier  to  read. 

Example  3-15.  Setting  the  argument  list  with  XtSetArg 

int  i; 

Arg  args [10] ; 

/*  Xtlnitialize  may  be  called  before  or  after  the  XtSetArg  calls  */ 


i  =  0; 
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Example  3-1 5.  Setting  the  argument  list  with  XtSetArg  (continued) 

XtSetArg(args[i] ,  XtNcallback,  (XtArgVal)  quit_callback_list) ; 
XtSetArg (args [i] ,  XtNsensitive,  (XtArgVal)  TRUE);  i++; 

banner  =  XtCreateManagedWidget ( 

banner,  /*  widget  name  */ 

commandWidgetClass,  /*  widget  class  from  Label. h  */ 

toplevel,  /*  parent  widget  */ 

args,  /*  argument  list  */ 

i  /*  arg  list  size  from  XtSetArg  counter  */ 
); 

Notice  that  i  is  used  as  the  number  of  arguments  in  the  XtCreateManagedWidget  call, 
not  xt Number.  xtNumber  would  in  this  case  return  the  value  10,  the  total  length  of  the 
Arg  array. 

Remember  that  i  must  be  incremented  outside  the  macro,  because  XtSetArg  references  its 
first  argument  twice.  The  following  code  will  not  work  because  xtNresource2  will  be  set 
into  widget_args  [2  ]  instead  of  widget_args  [  1] ,  as  desired.  Example  3-16  shows 
you  how  not  to  use  XtSetArg: 

Example  3-16.  Incorrectly  setting  the  argument  list  with  XtSetArg 

Arg  arg [10]  ; 
int  num_args; 

/*  This  example  will  NOT  work  correctly!  */ 
num_args  =0; 

/*  The  next  two  lines  are  wrong!  */ 

XtSetArg (args [num_args++] ,  XtNresourcel,  (XtArgVal)  10); 

XtSetArg (args [num_args++] ,  XtNresource2,  (XtArgVal)  40); 


The  xt  Set  Args  method  has  three  advantages  over  static  initialization: 

•  It  moves  the  code  that  sets  the  argument  list  closer  to  where  it  is  really  used  in  the  call 
to  create  a  widget 

•  It  allows  run-time  value  modification  using  the  same  method. 
The  same  storage  can  be  used  for  multiple  argument  lists. 

The  disadvantages  of  the  xt  Set  Args  method  are  as  follows: 

It  performs  all  assignments  at  run  time,  which  slows  startup  slightly. 

It  is  possible  to  try  to  set  more  arguments  than  space  has  been  allocated  for,  leading  to 
a  core  dump. 

It  is  possible  to  misplace  the  counter  increment,  leading  to  improper  operation. 

An  argument  list  and  a  counter  variable  must  be  kept  until  the  call  to  create  the  widget 
instance;  the  static  method  requires  keeping  only  the  argument  list. 
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•  It  may  waste  a  small  amount  of  storage  since  the  argument  list  array  is  usually  initial 
ized  larger  than  the  required  size. 

•  Lots  of  xt  Set Arg  calls  make  for  ugly  code. 

As  you  can  see,  these  differences  are  mostly  subjective,  and  you  may  use  whichever  method 
you  prefer,  or  some  combination. 

3.7.1 .2    Merging  Argument  Lists 

xtMergeArgLists  takes  two  argument  lists  and  counts  all  arguments,  allocates  the  stor 
age  for  a  single  argument  list  big  enough  to  hold  them,  and  stores  all  the  entries  from  both  in 
the  returned  argument  list.  It  does  not  remove  duplicate  entries.  The  calling  application  can 
use  xtNumber  to  determine  the  resulting  argument  count  (or  can  add  the  original  counts). 

3.7.2  The  Varargs  Interfaces 

A  varargs  interface  allows  a  function  to  be  called  with  a  variable  number  of  arguments.  This 
style  of  interface  is  standard  in  other  toolkits  like  XView,  since  it  is  much  more  convenient 
than  the  methods  of  setting  arguments  described  above.  It  allows  you  to  place  the 
resource/value  pairs  to  be  set  directly  into  the  call  to  create  a  widget,  instead  of  having  to 
store  them  into  an  intermediate  Arg  array  and  then  pass  the  array  to  xtCreateManaged- 
Widget. 

A  varargs  interface  to  Xt  has  been  developed  and  adopted  as  a  standard  for  R4.  In  addition, 
Dan  Heller  wrote  a  library  called  WidgetWrap  that  does  essentially  the  same  thing  and  is 
available  under  R3  (in  the  R3  distribution  in  the  directory  /contrib/widgets/widgetwrap). 

Example  3-17  and  Example  3-18  demonstrate  typical  calls  to  create  widgets  using  the  two 
varargs  interfaces  to  Xt. 

Example  3-17.  The  WidgetWrap  interface  to  creating  a  widget 
#include    "XI 1 /WidgetWrap. h" 


main(argc,  argv) 
int  argc; 
char  **argv; 
{ 

Widget  topLevel,  layout,  command; 


layout  =  WidgetCreate ("layout",  formWidgetClass,  topLevel,  NULL) 

command  =  WidgetCreate ("command",  commandWidgetClass,  topLevel, 
XtNwidth,          200, 
XtNheight,         200, 
XtNjustify,       XtJustifyCenter, 
XtNsensitivity,    TRUE, 
XtNlabel,          "Quit", 
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Example  3-17.  The  WidgetWrap  interlace  to  creating  a  widget  (continued) 

NULL) ; 


Example  3-18.  The  R4  varargs  interface  to  creating  a  widget 

main(argc,  argv) 
int  argc; 
char  **argv; 
{ 

Widget  topLevel,  layout,  command; 


layout  =  XtVaCreateManagedWidget ("layout",  formWidgetClass, 
topLevel,  NULL); 

command  =  XtVaCreateManagedWidget ("command",  commandWidgetClass, 
topLevel, 

XtNwidth,  200, 

XtNheight,  200, 

XtNjustify,  XtJustifyCenter, 

XtNsensitivity,  TRUE, 

XtNlabel,  "Quit", 
NULL) ; 


As  you  can  see,  there  are  two  varargs  interfaces,  and  they  are  identical  except  for  the  func 
tion  names  and  the  fact  that  WidgetWrap  requires  the  header  file  WidgetWrap.h.  The 
WidgetWrap  version  also  must  be  linked  with  the  module  WidgetWrap.o.  The  two  interfaces 
do  differ  in  some  respects,  but  these  cases  do  not  appear  often.  Code  using  WidgetWrap  can 
easily  be  converted  to  the  standard  library  for  Release  4. 

Note  that  the  last  argument  in  both  interfaces  is  NULL,  which  terminates  the  variable-length 
argument  list. 

The  varargs  interfaces  also  provide  varargs  versions  of  xtGetValues  and  xtSet- 
Values,  so  that  argument  lists  won't  be  needed  for  these  calls  either. 

The  varargs  interfaces  allow  you  to  specify  an  argument  list  if  you  wish,  so  that  if  you  have 
many  widgets  that  will  have  the  same  hardcoded  arguments,  you  can  create  one  argument  list 
and  pass  it  to  all  the  widget  creation  routines,  instead  of  adding  all  the  arguments  to  every 
widget  creation  routine.  The  R4  interface  even  allows  nested  argument  lists. 

Depending  on  how  you  use  them,  there  may  be  some  extra  overhead  involved  in  using  either 
varargs  interface,  because  they  massage  the  arguments  into  an  argument  list  and  call  xt- 
CreateWidget,  XtCreateManagedWidget,  XtSetValues,  or  XtGetValues. 
However,  the  added  convenience  seems  worth  it 
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3.8  Application  Contexts 

An  application  context  is  a  structure  maintained  by  Xt  that  stores  the  functions  registered  by 
the  application  and  other  information  about  the  application.  Primarily,  it  allows  Xt  applica 
tions  to  run  without  modification  on  certain  operating  systems  other  than  UNIX  that  do  not 
have  a  separate  address  space  for  each  process.  These  systems  include  the  Xerox  Cedar  envi 
ronment,  the  Symbolics  Genera  environment,  and  the  TI  Explorer  system.  Although  systems 
like  this  are  not  common,  the  goal  of  all  X  software  in  C  is  to  be  portable  to  any  system  that 
supports  C.* 

It  is  possible  to  create  more  than  one  application  context  within  a  single  program.  This  is 
rarely  done  and  its  implications  are  complex,  so  we  will  reserve  discussion  of  it  until  Section 
13.6. 

So  far  we  have  shown  you  only  routines  that  use  the  default  application  context  invisibly. 
Xt  initialize  creates  a  default  application  context,  and  several  other  routines  such  as 
xtAddActions  and  XtMainLoop  reference  it  internally.  However,  writing  an  applica 
tion  this  way  does  not  provide  the  desired  portability  to  the  systems  described  above.  There 
is  a  parallel  set  of  routines  to  the  ones  you  have  used,  that  have  an  explicit  application  con 
text  argument  For  reasons  that  have  to  do  with  the  efficiency  of  the  implementation  of  Xt, 
only  the  versions  that  have  an  explicit  argument  specifying  the  application  context  provide 
the  desired  portability.  The  parallel  routines  have  the  same  names,  but  with  App  inserted 
after  xt. 

The  first  argument  of  the  xtApp*  parallel  routines  is  an  application  context  ID  of  type  xt- 
AppContext.  After  that  they  have  the  same  calling  sequence  as  their  nonapp  counterparts. 
The  XtAppContext  ID  is  returned  by  XtCreateApplicationContext,  or  in  R4, 
by  XtAppInitialize. 

It  is  fine  to  use  the  routines  we  have  shown  while  developing  your  application.  But  when  it  is 
final,  you  should  convert  to  the  XtApp  routines.  Converting  to  the  xtApp  routines  is  a 
simple  process  in  R4,  but  a  bit  more  difficult  in  R3.  R4  provides  XtAppInitialize,  a 
routine  that  is  very  similar  to  xt  Initialize  except  that  its  first  argument  returns  the  xt- 
AppContext  that  will  be  used  in  subsequent  calls  to  other  functions.  (XtAppInitialize  also 
has  several  arguments  that  were  not  present  in  xt  initialize.)  In  R3,  to  use  explicit 
application  contexts  you  normally  have  to  call  four  separate  functions.  However,  we  have 
written  a  routine  called  RSlnitialize  that  does  this  for  you.  The  R3lnitialize 
convenience  function  is  shown  later  in  this  section.  Its  calling  sequence  is  identical  to  xt- 
Initialize  except  that  the  first  argument  (which  is  unused  in  xtlnitialize)  is 
replaced  by  an  argument  that  returns  the  application  context  ID.  (R3lnitialize  works 


*It  is  almost  a  maxim  that  there  is  no  such  thing  as  portable  software,  only  software  that  has  been  ported.  The  goal 
(and  more  or  less  the  reality)  of  X  is  that  the  porting  process  should  be  much  easier  than  it  has  traditionally  been,  and, 
most  important,  that  only  one  version  of  a  particular  piece  of  software  should  need  to  be  maintained.  The  various 
idiosyncrasies  of  particular  compilers  can  be  dealt  with  using  conditional  preprocessor  directives  (#ifdef).  X  features 
were  designed  specifically  to  provide  ways  to  handle  differences  in  screens  and  keyboards.  The  application  context 
is  an  effort  to  provide  a  way  to  handle  odd  operating  systems. 
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under  R4,  but  should  be  replaced  by  xtAppinitialize  to  avoid  waste.)  Example  3-19 
shows  the  code  necessary  to  modify  a  minimal  application  such  as  xbox  to  use  explicit  appli 
cation  contexts. 

Example  3-19.  Using  R3 Initialize  and  explicit  application  contexts 

main(argc,    argv) 
int   argc; 
char    **argv; 
{ 

Widget    topLevel; 

XtAppContext    app_con; 

/*    first   argument   of  Xtlnitialize   was   unused, 
*    replaced  by  app   context   return    */ 

topLevel   =   RSInitialize ( 

&app_con,  /*    application   context   return    */ 

"XBoxl",  /*    application   class   name    */ 

NULL,  /*    application    resources    (not    used)     */ 

0,  /*    application   resource   count    */ 

Sargc,  /*    command-line   argument   count    */ 

argv) ;  /*    command-line   string   */ 


||  XtAppMainLoop (app_con) ; 

Of  the  routines  you  have  seen  so  far  in  this  book,  only  xtMainLoop  and  xtAddActions 
have  versions  that  use  explicit  application  contexts:  XtAppMainLoop  and  xtAppAdd- 
Actions.  The  complete  list  of  routines  that  have  equivalents  is  presented  in  Section  13.6. 

Throughout  this  book  we  will  continue  to  use  the  routines  that  use  the  default  application 
context,  because  they  are  somewhat  less  cluttered,  and  because  they  work  in  both  R3  and  R4 
without  having  to  use  RSlnitialize. 

3.8.1    Xtlnitialize  Equivalents 

RSlnitialize  calls  a  combination  of  four  routines  instead  of  Xtlnitialize:  xt- 
Toolkitlnitialize,  XtCreateApplicationContext,  XtOpenDisplay, 
and  XtAppCreateShell.  Example  3-20  shows  the  RSlnitialize  routine. 

Example  3-20.  RSlnitialize:  a  substitute  for  Xtlnitialize  that  returns  an  explicit  application  con 
text 

tinclude  <Xll/Intrinsic.h> 
tinclude  <Xll/StringDefs.h> 
tinclude  <Xll/Shell .h> 

/*     Function  Name:  R3Initialize 

*  Description:  A  convience  routine  for  initializing  the  toolkit, 

*  for  use  in  R3  to  use  explicit  application  contexts 

*  Arguments:  app_context_return  -  The  application  context  of 

*  the  application 
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Example  3-20.  R3lnitialize:  a  substitute  for  Xtlnhialize  that  returns  an  explicit  application  con 
text  (continued) 


application_class 

options 

num_options 

argc_in_out, 
argv_in_out 
Returns:  The  shell  widget. 


-  The  class  of  the  application. 

-  The  option  list. 

-  The  number  of  options  in  the 
above  list 

-  number  and  list  of  command-line 
arguments . 


Widget 

RSlnitialize (app_context_return,  application_class,  options, 

num_options,  argc_in_out,  argv_in_out) 
XtAppContext  *  app_context_return; 
String  application_class; 
XrmOptionDescRec  *options; 
Cardinal  num_options,  *argc_in_out; 
String  *argv_in_out; 

XtAppContext  app_con; 
Display  *  dpy; 
Widget  root; 

XtToolkitlnitialize () ; 

app_con  =  XtCreateApplicationContext () ; 

dpy  =  XtOpenDisplay (app_con,  (String)  NULL,  NULL, 
application_class,  options,  num_options, 
argc_in_out,  argv_in_out) ; 

if  (dpy  ==  NULL) 

XtErrorMsg ("invalidDisplay", "xtlnitialize", "XtToolkitError", 
"Can't  Open  display",  (String  *)  NULL,  (Cardinal  *)NULL); 

root  =  XtAppCreateShell (NULL,  application_class, 

applicationShellWidgetClass,  dpy,  NULL,  0); 

if  (app_context_return  !=  NULL) 

*app_context_return  =  app_con; 

return (root) ; 

In  Release  4,  XtApplnitialize  provides  the  same  functionality  as  RSlnitialize 
and  more.  It  lets  you  pass  an  argument  list  for  the  shell  widget — which  neither  xt 
lnitialize  nor  RSlnitialize  allow. 

Note  that  the  XtOpenDisplay  routine  requires  an  XtAppContext  argument  This 
means  that  if  your  application  opens  a  connection  to  more  than  one  server,  it  must  use  expli 
cit  application  contexts.  The  topic  of  connecting  to  multiple  displays  is  discussed  more  fully 
in  Section  13.8. 
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An  Example  Application 


This  chapter  describes  a  complete  application,  in  several  iterations.  First,  it 
shows  a  simple  version  of  the  program,  a  bitmap  editor,  as  it  would  be  written 
assuming  the  existence  of  a  BitmapEdit  widget  (which  is  actually  developed  in 
Chapter  5).  Then,  two  refined  versions  are  developed,  each  demonstrating 
additional  Toolkit  programming  techniques.  Finally,  the  same  application  is 
shown  as  it  would  be  written  if  the  bitmap  editor  were  implemented  in  an  appli 
cation  window  rather  than  with  the  BitmapEdit  widget. 

In  This  Chapter: 

xbitmapl:  Bitmap  Editor  Using  a  BitmapEdit  Widget  104 

Widget  Public  Functions 106 

Application-defaults  File 107 

xbitmap2:  Adding  Scrollbars  to  Handle  Large  Bitmaps  107 

Overriding  Translations  112 

Action  Arguments  in  the  Translation  Table 113 

The  resize_thumbs  Action 113 

Scrollbar  Callbacks 114 

xbitmapS:  Adding  Graphics  to  Display  the  Bitmap 116 

Graphics  from  the  Application 119 

Writing  a  Bitmap  File 122 

xbitmap4:  Bitmap  Editor  Without  a  BitmapEdit  Widget  123 


Enough  of  these  trivial  programs!  Now  for  an  (almost)  real  application.  This  chapter 
describes  the  development  of  a  bitmap  editor.  Although  it  is  simple,  it  can  be  easily  extended 
to  be  quite  powerful  without  any  new  techniques. 

We  will  show  several  versions  of  xbitmap,  beginning  with  a  simple  version  that  assumes  the 
existence  of  a  BitmapEdit  widget  (which  will  actually  be  developed  in  Chapters  5  and  6). 
Subsequent  versions  add  scrollbars,  then  add  two  widgets  that  display  the  bitmap  in  small 
scale  (one  normal,  one  reverse  video),  and  finally  implement  the  same  application  without 
the  use  of  the  specialized  BitmapEdit  widget 

These  examples  will  demonstrate  the  techniques  described  in  Chapters  2  and  3  as  they  would 
appear  in  a  real  application,  and  will  bring  up  a  number  of  new  topics: 

•  The  initial  version  introduces  the  bitmap  editor  application,  and  demonstrates  how  the 
application  can  access  the  data  within  a  widget  using  a  public  function  defined  by  the 
widget  class. 

•  The  second  version,  which  adds  scrollbars,  shows  how  scrollbars  are  linked  to  the  win 
dow  that  they  control. 

•  The  third  version  demonstrates  two  ways  of  adding  the  small-scale  bitmaps,  one  using  a 
standard  widget  and  one  drawing  into  a  Core  widget  from  the  application. 

•  The  fourth  version  does  not  use  the  BitmapEdit  widget,  but  instead  implements  its  fea 
tures  by  drawing  into  a  Core  widget  This  demonstrates  how  to  prototype  features  and 
prepare  for  writing  your  own  widget  It  also  allows  us  to  describe  the  code  necessary  to 
implement  the  bitmap  editor  so  that  you  will  already  understand  this  code  when  you  see  it 
in  the  internal  framework  of  a  widget  described  in  Chapters  5  and  6. 

This  chapter  demonstrates  that  there  are  several  ways  to  add  any  given  feature,  and  describes 
the  tradeoffs  between  the  different  options.  Many  features  can  be  added  from  the  application 
code  by  creating  a  Core  widget  to  draw  into,  or  by  creating  a  custom  widget  By  the  end  of 
Chapters  5  and  6,  you  will  have  seen  how  to  implement  this  application  entirely  with  existing 
widgets  and  application  code,  how  to  implement  it  using  custom  widgets,  and  how  to  imple 
ment  a  mixture  of  the  two. 
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4.1   xbitmapl :  Bitmap  Editor  Using  a  BitmapEdit  Widget 

The  screen  appearance  of  xbitmapl  is  shown  in  Figure  4-1.  As  usual,  it  is  a  good  idea  to 
compile  and  run  each  example  as  it  is  discussed.* 


Figure  4-1.  xbitmapl:  how  it  looks  on  the  screen 

The  BitmapEdit  widget  lets  you  set  bits  in  the  visible  bitmap  by  clicking  the  first  pointer  but 
ton  or  dragging  the  pointer  with  the  first  button  held  down,  lets  you  erase  bits  using  the  sec 
ond  button,  or  lets  you  toggle  bits  using  the  third  button.  The  "Print  Output"  button  simply 
prints  on  the  standard  output  an  array  of  1's  and  O's  representing  the  set  and  unset  bits  in  the 
bitmap.  (Code  to  read  and  write  standard  XI 1  bitmap  files  is  added  in  a  later  version.) 

xbitmapl  consists  of  only  five  widgets  other  than  the  top-level  Shell;  one  Form,  one  Box,  one 
BitmapEdit,  and  two  Command  widgets.  The  Form  widget  is  the  child  of  the  Shell  widget. 
One  child  of  the  Form  widget  is  a  Box  containing  the  two  Command  widgets,  and  the  other  is 
the  BitmapEdit  widget  This  arrangement  of  geometry-managing  widgets  keeps  the  appear 
ance  of  the  application  neat  even  when  the  application  is  resized. 

The  code  for  xbitmapl  is  shown  in  Example  4-1.  One  new  technique  shown  in  this  example 
is  the  use  of  the  public  function  BitmapEditGetArrayString  defined  by  the  Bitmap- 
Edit  widget  This  function  allows  an  application  callback  function  to  access  the  BitmapEdit 
widget's  private  data.  Even  though  the  array  of  bits  in  the  bitmap  is  a  resource  of  the 
BitmapEdit  widget  that  can  be  read  with  xtGetValues,  this  public  function  provides  a 

*How  to  get  and  compile  the  example  source  code  is  described  in  the  Preface  and  Section  2.3.2. 
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more  convenient  way  for  the  application  to  get  the  contents  of  the  bitmap  so  that  it  can  print 
them  out 

Example  4-1.  xbitmapl:  complete  code 

/* 

*  xbitmap.c  —  an  example  application 
*/ 

tinclude  <stdio.h> 
tinclude  <Xll/Intrinsic.h> 
tinclude  <Xll/StringDef s .h> 

tifdef  X11R4 

tinclude  <Xll/Xaw/Form.h> 

tinclude  <Xll/Xaw/Box.h> 

tinclude  <Xll/Xaw/Command.h> 

telse 

tinclude  <Xll/Form.h> 

tinclude  <Xll/Box.h> 

tinclude  <X11 /Command. h> 

tendif  /*  X11R4  */ 

tinclude  "BitmapEdit .h" 

Dimension  pixmap_width_in_cells,  pixmap_height_in_cells; 

/* 

*  The  printout  routine  prints  an  array  of  1's  and  O's  representing 

*  the  contents  of  the  bitmap.   This  data  can  be  processed  into  any 

*  desired  form,  including  standard  Xll  bitmap  file  format. 
*/ 

/*  ARGSUSED  */ 

static  void 

printout (widget,  client_data,  call_data) 

Widget  widget; 

caddr_t  client_data,  call_data;  /*  unused  */ 

{ 

int  x,  y; 

char  *cell; 

cell  =  BitmapEditGetArrayString (widget) ; 

(void)  putchar ('\n' ); 

for  (y  =  0;  y  <  pixmap_height_in  cells;  y++)  { 
for  (x  =  0;  x  <  pixmap_width_in_cells;  x++) 

(void)  putchar (cell [x  +  y  *  pixmap_width_in_cells] 

?  '  1 '  :  '  0 ' )  ; 
(void)  putchar ('\n') ; 
} 

(void)  putchar ('\n' ); 
} 

main(argc,  argv) 
int  argc; 
char  *argv[] ; 
{ 

Widget  topLevel,  form,  buttonbox,  quit,  output,  bigBitmap; 

int  i; 

Arg  arg[5]; 
extern  exit () ; 
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Example  4-1.  xbitmapl:  complete  code  (continued) 


static  XrmOptionDescRec  tablet]  =  { 

{"-pw",  "*pixmapWidthInCells", 

{ "-pixmapwidth",  '^pixmapWidthlnCells", 
{"-ph",  "*pixmapHeightInCells' 

{ "-pixmapheight", n*pixmapHeightInCells' 
{"-cellsize",     "*cellSizeInPixels", 


XrmoptionSepArg,  NULL}, 

XrmoptionSepArg,  NULL}, 

XrmoptionSepArg,  NULL}, 

XrmoptionSepArg,  NULL}, 

XrmoptionSepArg,  NULL}, 


topLevel  =  Xtlnitialize (argv [0] ,  "XBitmapl1 
XtNumber (table) ,  &argc,  argv); 


table, 


} 


form  =  XtCreateManagedWidget ("form",  formWidgetClass, 
topLevel,  NULL,  0) ; 

buttonbox  =  XtCreateManagedWidget ("buttonbox",  boxWidgetClass, 
form,  NULL,  0) ; 

output  =  XtCreateManagedWidget ("output",  commandWidgetClass, 
buttonbox,  NULL,  0) ; 

XtAddCallback (output,  XtNcallback,  printout,  NULL); 

quit  =  XtCreateManagedWidget ("quit",  commandWidgetClass, 
buttonbox,  NULL,  0); 

XtAddCallback (quit,  XtNcallback,  exit,  NULL); 

bigBitmap  =  XtCreateManagedWidget ("bigBitmap", 
bitmapEditWidgetClass,  form,  NULL,  0); 

/*  need  the  following  values  for  the  printout  routine.  */ 

i  =  0; 

XtSetArg(arg[i] ,  XtNpixmapWidthlnCells, 

&pixmap_width_in_cells) ;   i++; 
XtSetArg(arg[i] ,  XtNpixmapHeightlnCells, 

&pixmap_height_in_cells) ; 
XtGetValues (bigBitmap,  arg,  i) ; 

XtRealizeWidget (topLevel) ; 
XtMainLoopO  ; 


You  should  recognize  the  options  table  as  the  one  described  in  Section  3.6.2.  Note  that 
xbitmapl  does  not  require  application  resources,  because  there  is  nothing  for  them  to  set 
The  widgets  themselves  provide  all  needed  resources. 


4.1.1    Widget  Public  Functions 

Public  functions  are  supplied  by  a  widget  class  when  it  wants  certain  data  to  be  readable  or 
writable  by  the  application,  but  for  some  reason  does  not  want  the  data  both  readable  and 
writable  as  would  be  the  case  if  it  were  a  resource.  Sometimes  the  application  needs  to  be 
able  to  read  data  but  not  write  it  At  other  times,  a  widget  class  has  features  that  it  wants  con 
trollable  from  the  application  but  never  user-customizable  (because  they  are  meaningless  at 
startup,  for  example),  and  therefore  it  provides  a  function  for  setting  them. 
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The  BitmapEdit  widget  provides  a  public  function  because  this  version  does  not  allow  the 
application  to  set  the  bitmap,  and  because  it  is  easier  for  the  programmer  to  get  the  array  with 
a  specialized  function  than  through  xt  Get  Values.  A  more  complete  bitmap  editor  widget 
would  need  to  make  the  array  of  bits  a  resource,  so  that  the  application  could  read  bitmap 
files. 


4.1.2   Application-defaults  File 

Example  4-2  shows  the  application-defaults  file  for  xbitmapl .  It  sets  the  text  in  the  Com 
mand  widgets,  the  size  in  cells  of  the  bitmap,  the  size  in  pixels  of  each  cell  in  the  bitmap,  and 
the  foreground  color,  and  constrains  the  bigBitmap  widget  to  appear  below  the  button 
box.  Without  this  constraint,  the  Form  widget  would  place  the  button  box  overlapping  big- 
Bitmap  instead  of  above  it 

Example  4-2.  XBitmapl:  application-defaults  file 

*quit*label:   Quit 
*output*label :     Print  Array 
*cellSizeInPixels: 30 
*pixmapWidthInCells:    20 
*pixmapHeightInCells:   20 
*foregroundPixel:  blue 
*buttonbox. width:  200 
*bigBitmap*fromVert :    buttonbox 


4.2  xbitmap2:  Adding  Scrollbars  to  Handle  Large  Bitmaps 

xbitmapl  always  displayed  all  the  cells  in  the  bitmap  being  edited.  This  can  be  inconvenient 
when  the  bitmap  is  large.  For  example,  this  makes  it  difficult  to  edit  any  bitmap  larger  than 
one-fifth  of  the  screen  (because  each  cell  takes  up  a  minimum  of  five  pixels).  The  solution  to 
this  problem  is  to  add  scrollbars,  and  to  display  only  part  of  the  bitmap  at  a  time.  We'll  add 
this  feature  to  develop  xbitmap2,  shown  in  Figure  4-2. 

The  easy  way  to  add  scrollbars  is  to  use  a  widget  provided  just  for  this  purpose,  such  as  the 
Athena  Viewport  widget  Simply  by  inserting  a  Viewport  widget  into  the  instance  hierarchy 
between  the  Form  widget  and  the  BitmapEdit  widget  and  providing  the  right  resource  set 
tings,  scrollbars  will  appear  around  the  BitmapEdit  widget  This  example  program  is 
included  with  the  source  distribution  as  xbitmapS,  but  is  not  described  here  because  it  is  a 
simple  improvement  from  xbitmapl . 
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Print  Array     Quit 


Figure  4-2.  xbitmap2:  scrollbars  added 

The  Viewport  widget,  like  the  Dialog  widget  described  in  the  last  chapter,  is  really  just  a 
Form  widget,  two  Scroll  widgets,  and  the  code  to  link  them  together.  The  window  displayed 
is  blank  until  you  create  a  widget  like  BitmapEdit  as  a  child  of  Viewport  This  child  can  be  a 
composite  widget  with  children  of  its  own,  if  desired.* 

As  an  exercise,  we'll  pretend  that  we  don't  have  the  Viewport  widget;  we'll  create  scrollbars 
and  link  them  with  the  BitmapEdit  widget  directly  from  the  application.  Scrollbars  are  inter 
esting  because  they  need  to  be  very  tightly  coupled  with  the  window  they  are  controlling. 
Whenever  the  user  clicks  or  drags  in  the  scrollbar,  the  controlled  window  must  quickly 
redisplay  the  correct  part  of  its  contents.  Each  scrollbar  widget  provides  at  least  two  call 
backs:  one  for  jump  scrolling  and  one  for  smooth  scrolling.  Typically,  the  first  and  third  but 
tons  initiate  jump  scrolling  by  one  screenful  up  and  down,  respectively,  while  the  second  but 
ton  moves  the  thumb  to  the  pointer  position  and  smoothly  scrolls  the  window  up  or  down  if 
the  pointer  is  dragged  while  the  button  is  held  down. 


*Of  course,  it  is  also  possible  to  create  a  widget  similar  to  Viewport  that  combines  BitmapEdit  and  scrollbars  into  a 
single  unit  This  widget  could  be  a  subclass  of  a  geometry  managing  widget  such  as  Form,  and  would  create  a 
BitmapEdit  widget  and  the  scrollbar  widgets  as  children.  It  would  add  the  code  necessary  to  create  the  child  widgets 
and  link  the  scrollbars  with  BitmapEdit.  This  widget  is  described  in  Chapter  1 1 ,  Geometry  Management. 
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The  application  controls  the  position  and  length  of  the  scrollbar  thumb.  The  length  of  the 
thumb  must  reflect  the  percentage  of  the  data  that  is  currently  in  view,  and  the  position  must 
reflect  the  current  position  in  the  data.  Only  the  application  knows  how  much  data  there  is: 
The  application  must  set  the  thumb  as  the  scrollbar  widget  is  created,  and  reset  the  thumb  in 
each  of  its  callbacks.  When  the  scrollbars  are  resized,  this  indicates  that  the  accompanying 
window  has  also  been  resized,  and  therefore  the  portion  of  the  data  being  shown  has  changed. 
Therefore,  the  thumb  must  also  be  reset  in  the  procedure  that  handles  resizes. 

We  will  use  the  Athena  Scroll  widget  class  in  this  example.  Before  proceeding  further,  it 
might  be  helpful  to  read  the  Scroll  widget  reference  page  in  Volume  Five,  X  Toolkit  Intrinsics 
Reference  Manual,  to  get  an  understanding  of  the  basic  operation  of  the  widget.  Other 
widget  sets  have  scrollbar  widgets  that  interact  with  the  application  in  similar  ways. 

•  Two  Scroll  widgets  are  created,  one  for  horizontal  and  one  for  vertical  scrolling. 

•  Another  level  of  composite  widget  (a  Form  widget)  is  added  to  manage  the  BitmapEdit 
widget  and  Scroll  widgets  as  a  unit.  The  instance  hierarchy  ofxbitmap2  is  shown  in  Fig 
ure  4-3. 

•  Two  callback  functions  are  added  for  each  scrollbar,  to  perform  the  two  kinds  of  scrolling 
(smooth  and  jump  scrolling). 

•  An  action  is  created  to  reset  the  scrollbar  thumbs  when  the  application  is  resized.  This 
action  is  registered  with  Xt  as  usual,  and  added  to  the  existing  translation  table  of  the 
Scroll  widgets  using  XtOverrideTranslations. 
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Figure  4-3.  The  instance  hierarchy  ofxbitmap2 

Example  4-3  shows  the  code  needed  to  add  scrollbars  to  xbitmopl . 

Example  4-3.  xb'rtmap2:  adding  scrollbars 

create_viewport (parent) 

Widget  parent; 

{ 

Widget  scrollHoriz,  scrollVert,  drawingForm; 

Arg  args [6] ; 

int  i; 

int  cell_size; 

static  XtActionsRec  window_actions [ ]  =  { 
{ "resize_thumbs",  resize_thumbs} 

}; 

XtAddActions (window_actions,  1); 

drawingForm  =  XtCreateManagedWidget ("drawingForm", 
formWidgetClass,  parent,  NULL,  0) ; 

bigBitmap  =  XtCreateManagedWidget ("bigBitmap", 

bitmapEditWidgetClass,  drawingForm,  NULL,  0); 

i  =  0; 

XtSetArg(args[i] ,  XtNpixmapHeightlnCells, 
&pixmap_height_in_cells) ; 
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Example  4-3.  xbitmap2:  adding  scrollbars  (continued) 

XtSetArg(args[i]  ,  XtNpixmapWidthlnCells, 

&pixmap_width_in_cells)  ;   i++; 

XtSetArg(args[i]f  XtNcellSizelnPixels,  &cell_size)  ; 
XtGetValues(bigBitmap,  args,  i)  ; 

pixmap_height_in_j>ixels   =   pixmap_height_in_cells    *    cell    size; 
pixmap_width_in_pixels   =  pixmap_width_in_cells    *    cell_sTze; 

window_width  =  (  (pixmap_width_in_pixels  >  MAXSIZE)  ?  MAXSIZE 

:  pixmap_width_in_pixels)  ; 
window_height  =  (  (pixmap_height_injpixels  >  MAXSIZE)  ?  MAXSIZE 

:  pixmap_height_injpixels)  ; 

i  =  0; 

XtSetArg(args[i]  ,  XtNwidth,  window_width)  ; 
XtSetArg(args[i]  ,  XtNheight,  window_height)  ; 
XtSetValues  (bigBitmap,  args,  i)  ; 

i  =  0; 

XtSetArg(args[i]  ,  XtNorientation,  XtorientVertical)  ; 
XtSetArg(args[i]  ,  XtNheight,  window_height)  ; 
XtSetArg(args[i]  ,  XtNwidth,  15);    i++; 
XtSetArg(args[i]  ,  XtNshown, 

window_height/pixmap_height_in_pixels)  ; 


scrollVert  =  XtCreateManagedWidget  ("scrollVert", 
scrollbarWidgetClass,  drawingForm,  args,  i)  ; 

XtAddCallback  (scrollVert,  XtNscrollProc,  scroll_up_down, 

bigBitmap)  ; 
XtAddCallback  (scrollVert,  XtNthumbProc,  thumb_up_down, 

bigBitmap)  ; 

XtOverrideTranslations  (scrollVert, 

XtParseTranslationTable  ("<Configure>:  resize_thumbs  (v)  ")  ) 

i  =  0; 

XtSetArg(args[i]  ,    XtNorientation,    XtorientHorizontal)  ; 
XtSetArg(args[i]  ,    XtNwidth,    window_width)  ; 
XtSetArg(args[i],    XtNheight,    15);         i++; 
XtSetArg(args[i]  ,    XtNshown, 

window_height/pixmap_height_in_pixels)  ; 

scrollHoriz   =  XtCreateManagedWidget  ("scrollHoriz", 
scrollbarWidgetClass,    drawingForm,    args,    i)  ; 

XtAddCallback  (scrollHoriz,    XtNscrollProc,    scroll_left_right, 

bigBitmap)  ; 
XtAddCallback  (scrollHoriz,    XtNthumbProc,    thumb_left_right, 

bigBitmap)  ; 
XtOverrideTranslations  (scrollHoriz, 

XtParseTranslationTable  ("<Conf  igure>:    resize_thumbs  (h)  ")  )  ; 
} 

The  create_viewport  routine  is  called  from  main  just  before  calling  XtRealize- 
widget  and  XtMainLoop.  Think  of  it  as  a  substitute  for  the  call  that  created  the  Bitmap- 
Edit  widget  alone.  It  is  passed  the  parent  widget,  which,  as  in  xbitmopl  ,  is  a  Form  widget 
whose  other  child  is  a  Box  containing  Command  widgets.  create_viewport  creates 
another  Form  widget  to  manage  the  Scroll  widgets  and  the  BitmapEdit  widget.  The  routine 
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next  gets  the  pixmap  dimensions  and  cell  size  from  the  BitmapEdit  widget;  these  will  be 
needed  in  several  places  in  the  application,  such  as  in  the  code  that  makes  the  scrollbars  the 
same  size  as  the  BitmapEdit  widget 

Next,  create_viewport  creates  an  argument  list  for  each  call  to  create  a  scrollbar.  The 
arguments  set  the  length  and  width  of  each  scrollbar,  its  orientation,  and  the  length  of  the 
thumb  (the  xtNshown  resource).  After  creating  each  widget,  the  application's  two  callback 
functions  are  registered  for  that  widget  Notice  that  the  ID  of  the  BitmapEdit  widget  is 
passed  to  the  callback  functions.  The  callback  functions  will  use  this  information  to  get 
resource  values  from  the  BitmapEdit  widget 

The  resize_thumbs  action  (shown  in  Section  4.2.3)  simply  resets  the  length  of  the 
thumb  to  represent  the  current  amount  of  the  data  being  shown,  using  a  public  function  of  the 
Scroll  widget  It  is  invoked  whenever  the  scrollbars  are  resized,  because  when  the  scrollbars 
change  size  that  means  the  viewing  window  also  changed  size  and  now  displays  a  different 
portion  of  the  bitmap.  The  event  that  indicates  that  a  widget  has  been  resized  is  the 
Conf  igureNotif  y  event,  indicated  in  the  translation  table  as  Configure. 

4.2.1    Overriding  Translations 

Finally,  create_viewport  calls  XtOverrideTranslations  to  make  Xt  call  the 
application  function  resize_thumbs  in  response  to  resize  and  expose  events.  The 
res ize_t numbs  routine  sets  the  thumb  to  the  proper  length  (and  as  a  side  effect,  the 
Scroll  widget  redraws  the  thumb).  This  brings  up  a  number  of  questions.  Why  call  Xt 
OverrideTranslations  instead  of  XtSetValues?  Also,  this  translation  table 
includes  action  functions  with  arguments.  How  do  these  work? 

Setting  the  xtNtranslations  resource  of  a  widget  replaces  the  existing  translations  of 
that  widget  The  problem  in  this  case  is  that  there  is  no  reason  to  reset  translations  that  we 
don't  need  to  change  but  that  the  Scroll  widgets  need  to  function.  Furthermore,  we  want  the 
user  to  be  able  to  configure  certain  translations,  but  not  the  ones  that  are  essential  if  the  appli 
cation  is  to  function.  That's  why  Xt  provides  two  functions  for  adding  translations  to  an 
existing  table:  XtOverrideTranslations  and  XtAugmentTranslations. 
Actions  do  not  work  like  callback  lists — there  can  be  only  one  action  mapped  to  a  particular 
event  or  event  sequence.  The  difference  between  XtOverrideTranslations  and  Xt 
AugmentTranslations  is  in  what  happens  when  both  the  new  and  existing  translation 
tables  have  an  entry  for  the  same  event  sequence,  but  a  different  action.  XtAugment 
Translations  uses  the  old  translation,  whereas  XtOverrideTranslations  uses 
the  new  translation. 

You  should  be  careful  when  using  XtOverrideTranslations  not  to  override  any 
translations  that  a  widget  depends  on  to  function.  In  this  case,  the  application  overrides  the 
translation  that  invokes  the  Scroll  widget's  expose  and  resize  code,  but  this  is  acceptable 
because  Scroll  does  not  depend  on  this  code.  The  Scroll  widget  automatically  redraws  its 
contents,  the  thumb,  in  response  to  the  Scroll  widget's  public  function  XawScrollBar- 
SetThumb.  As  long  as  the  application  takes  over  the  responsibility  to  call  this  at  the  right 
times,  the  Scroll  widgets  will  be  properly  updated. 
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Action  Arguments  in  the  Translation  Table 

Notice  that  the  translation  tables  specified  in  the  calls  to  xtOverrideTranslations  in 
Example  4-4  supply  either  a  v  or  an  h  argument  to  the  action  routine  resize_thumbs. 
Xt  passes  this  argument  as  the  call_data  argument  to  the  action  routine.  This  trick  sim 
ply  allows  one  action  routine  to  serve  both  the  horizontal  and  vertical  scrollbars.  This  code 
could  also  have  been  written  with  two  independent  action  routines.  It  is  better  to  have  inde 
pendent  action  routines  when  the  applicable  translations  are  user-configurable  (which  they 
are  not,  in  this  case). 

Remember  that  since  the  translation  table  is  a  string,  the  argument  placed  in  the  translation 
table  is  passed  to  the  action  routine  as  a  string.  This  argument,  therefore,  is  basically  a  con 
stant  hardcoded  into  each  translation  table.  It  cannot  be  used  in  the  same  way  that  the 
client_data  argument  of  callback  functions  can  be  used,  to  pass  general  data  into  an 
action  routine. 

The  action  argument  is  not  limited  to  a  single  string.  You  can  place  a  series  of  words 
separated  by  spaces  between  the  parentheses  after  an  action  in  the  translation  table.  These 
words  will  be  passed  into  the  action  in  the  third  argument,  pa  rams,  which  is  an  array  of 
strings  just  like  argv.  The  fourth  argument  is  the  number  of  parameters,  num_j)arams, 
analogous  to  argc.  This  multiple-parameter  feature  is  rarely  used. 

Also  remember  that  translation  tables  must  be  compiled  with  xtParseTranslation- 
Table  before  passing  them  to  XtOverrideTranslations,  xtAugment- 
Translations,  or  in  an  argument  list  passed  to  XtSetValues. 


4.2.3   The  resize_thumbs  Action 

Now,  let's  move  on  to  the  routine  referenced  in  this  translation  table,  resize_thumbs. 
Example  4-4  shows  this  code.  It  simply  sets  the  thumb  of  either  scrollbar  based  on  the  cur 
rent  position  of  the  data  and  the  size  of  the  BitmapEdit  widget's  window. 

Example  4-4.  xbitmap2:  resize_thumbs  routine 

/*  ARGSUSED  */ 

static  void 

resize_thumbs (w,  event,  orientation) 

Widget  w; 

XEvent  *event; 

char  *orientation[] ;    /*  String  *params;  */ 

/*  Cardinal  num_params;  (not  needed)   */ 

{ 

Dimension  width,  height; 
int  cur_x,  cur_y; 
Arg  args [5] ; 
int  i; 

i  =  0; 

XtSetArg(args[i] ,  XtNheight,  Sheight) ; 

XtSetArg(args[i],  XtNwidth,  Swidth) 

XtSetArg(args[i],  XtNcurX,  &cur_x) ; 
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Example  4-4.  xbitmap2:  resizejthumbs  routine  (continued) 

XtSetArg(args[i] ,  XtNcurY,  &cur_y) ;   i++; 
XtGetValues (bigBitmap,  args,  i)  ; 

if  (*orientation[0]  ==  'h') 
fifdef  X11R4 

XawScrollBar Set Thumb (w, 
#else 

XtScrollBarSetThumb (w, 
#endif  /*  X11R4  */ 

(float)cur_x/pixmap_width_in_pixels, 

(float) width/pixmap_width_in_pixels) ; 
else 
tifdef  X11R4 

XawScrollBarSetThumb (w, 
felse 

XtScrollBarSetThumb (w, 
#endif  /*  X11R4  */ 

(float)cur_y/pixmap_height_in_pixels, 

(float) height/pixmap_height_in_pixels) ; 
} 

The  XawScrollBarSetThumb  routine  is  defined  by  the  Scroll  widget  class.*  It  provides 
an  easy  method  for  applications  to  set  the  position  and  length  of  the  thumb.  The  Scroll 
widget  also  has  resources  that  set  these  same  parameters. 

Note  that  re size_t bombs  is  called  in  response  to  Expose  events  as  well  as  during 
resizing.  This  is  because  the  application  never  knows  exactly  how  much  screen  space  it  will 
be  allocated  by  the  window  manager.  Its  size  when  it  appears  on  the  screen  may  not  be  the 
size  specified  in  the  code  or  in  the  resource  databases  since  the  user  may  intervene  to  resize 
the  application  between  two  existing  windows.  Therefore,  it  is  futile  to  set  the  thumb  when 
the  Scroll  widgets  are  created,  because  the  size  of  the  thumbs  has  to  be  recalculated  based  on 
the  current  size  of  the  window. 


4.2.4   Scrollbar  Callbacks 

The  callback  functions  for  each  scrollbar  are  very  similar  to  resize_thumbs.  They  also 
reset  the  thumb,  but  add  code  that  moves  the  thumb  in  proportion  to  the  pointer  position. 
Example  4-5  shows  the  callback  functions  for  the  vertical  scrollbar.  The  horizontal  scrollbar 
has  two  analogous  callback  functions. 

Example  4-5.  xbitmap2:  scrolling  callback  functions 

/*  ARGSUSED  */ 

static  void 

scroll_up_down (w,  unused,  pixels) 


*In  Release  3  and  earlier,  all  public  functions  declared  by  widgets  in  the  Athena  widget  set  had  the  Xt  prefix.  This 
was  incorrect  Only  routines  defined  by  the  Xt  library  should  have  the  Xt  prefix,  because  it  is  important  to  distinguish 
the  fact  that  Xt  routines  are  an  X  Consortium  standard,  while  the  Athena  widgets  are  not  Public  functions  defined  by 
other  widget  sets  will  have  their  own  distinctive  prefix.  As  of  Release  4,  all  Athena  widget  public  functions  have  the 
prefix  Xaw. 
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Example  4-5.  xbitmap2:  scrolling  callback  functions  (continued) 

Widget  w; 
caddr_t  unused; 
int  pixels; 
{ 

Dimension  height; 

int  cur_y; 

Arg  args [5] ; 

int  i; 

i  =  0; 

XtSetArg(args[i] ,  XtNheight,  sheight) ; 
XtSetArg(args[i] ,  XtNcurY,  &cur_y) ; 
XtGetValues(bigBitmap,  args,  i); 

/*  When  pixels  is  negative,  right  button  pressed,  move 

*  data  down,  thumb  moves  up.   Otherwise,  left  button 

*  pressed,  pixels  positive,  move  data  up,  thumb  down. 
*/ 

cur_y  +=  pixels; 

/*  limit  panning  to  size  of  bitmap  */ 
if  (cur_y  <  0) 

cur_y  =  0; 
else  if  (cur_y  >  pixmap_height_in_pixels  -  height  ) 

cur_y  =  pixmap_height_in_pixels  -  height; 

i  =  0; 

XtSetArg(args[i] ,  XtNcurY,  cur_y) ;    i++; 

XtSetValues (bigBitmap,  args,  i)  ; 

#ifdef  X11R4 

XawScrollBarSetThumb (w, 
telse 

XtScrollBarSetThumb (w, 
#endif  /*  X11R4  */ 

(float) cur_y/pixmap_height_in_pixels, 
(float ) height/pixmap_height_in_pixels) ; 
} 

/*  ARGSUSED  */ 

static  void 

thumb_up_down (w,  unused,  percent) 

Widget  w; 

caddr_t  unused; 

float  percent; 

{ 

Dimension  height; 

int  cur_y; 

Arg  args [5]  ; 

int  i; 

i  =  0; 

XtSetArg(args[i]  ,  XtNheight,  &height)  ;   i-H-; 
XtSetArg(args[i] ,  XtNcurY,  &cur_y) ;   i++; 
XtGetValues (bigBitmap,  args,  i) ; 

if  ( (cur_y  =  (int) (pixmap_height_in_pixels  *  percent) )  >= 

pixmap_height_in_pixels  -  height) 
cur_y  =  pixmap_height_in_pixels  -  height; 
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Example  4-5.  xbitmap2:  scrolling  callback  functions  (continued) 

i  =  0; 

XtSetArg(args[i]  ,  XtNcurY,  cur_y) ;    i++; 

XtSetValues (bigBitmap,  args,  i)  ; 

tifdef  X11R4 

XawScrollBarSetThumb (w, 
telse 

XtScrollBarSetThumb (w, 
#endif  /*  X11R4  */ 

(f loat)cur_y/pixmap_height_in_pixels, 
(f loat)height/pixmap_height_in_pixels) ; 
} 

Note  that  the  scroll_up_down  callback  is  called  with  the  pixels  argument,  which 
describes  the  vertical  position  of  the  button  press  from  the  top  of  the  widget.  If  the  left  but 
ton  was  pressed,  this  number  is  positive,  and  for  the  right  button  it  is  negative.  This  routine 
moves  the  thumb  by  this  amount,  unless  the  data  being  shown  is  already  at  one  of  the 
extremes.  In  effect,  the  thumb  and  data  are  moved  an  amount  proportional  to  the  vertical  dis 
tance  between  the  top  of  the  scrollbar  and  the  point  where  the  button  press  occurred. 

The  thumb_up_down  callback  moves  the  top  of  the  thumb  to  the  position  where  the  but 
ton  press  occurred.  Since  this  callback  is  called  repeatedly  if  the  pointer  is  dragged  while  the 
button  is  pressed,  it  lets  the  user  scan  up  and  down  through  the  data. 

Notice  that  both  callback  functions  set  the  cur_x  and  cur_y  resources  of  BitmapEdit. 
This  is  how  the  application  tells  BitmapEdit  which  part  of  the  bitmap  to  display.  You'll  see 
how  this  works  in  Section  4.4,  where  the  code  to  implement  the  bitmap  editor  from  the  appli 
cation  is  described. 


4.3  xbitmapS:  Adding  Graphics  to  Display  the  Bitmap 

In  addition  to  displaying  the  bitmap  in  editable  form,  with  one  cell  for  each  pixel  in  the 
actual  bitmap,  a  bitmap  editor  should  also  display  an  image  in  true  scale  that  shows  what  the 
bitmap  really  looks  like  when  displayed  on  the  screen.  It  is  customary  to  present  this  bitmap 
in  both  normal  and  reverse  video,  and  update  it  every  time  the  user  toggles  a  cell  in  the 
enlarged  bitmap.  Figure  4-4  shows  the  appearance  of  the  application  with  this  feature  added. 
There  are  two  ways  to  implement  this  behavior.  One  is  to  use  the  Label  widget,  which  can 
display  a  pixmap  instead  of  a  string.  The  other  is  to  draw  into  a  Core  widget.  From  the  point 
of  view  of  the  user,  both  would  look  exactly  the  same. 

Implementing  this  feature  with  Label  widgets  is  straightforward;  the  application  creates  two 
pixmaps  of  the  proper  size,  and  sets  the  xtNpixmap  resources  of  two  Label  widgets  to  dis 
play  them.  The  problem  comes  when  trying  to  update  this  display  each  time  a  cell  is  toggled. 
We  can  easily  draw  the  changed  pixel  into  the  small  pixmaps,  but  without  a  push  the  Label 
widget  won't  redisplay  the  pixmap.  Because  the  XtNpixmap  resource  is  not  chang 
ing — the  same  pixmap  ID  is  used  for  the  life  of  the  application — the  Label  widget  is  not 
notified  by  Xt  that  the  pixmap  has  been  drawn  into.  There  are  two  ways  to  make  the  existing 
Label  widget  redraw  the  pixmap;  one  is  to  clear  its  window  using  an  Xlib  routine  that 
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Figure  4-4.  xbitmapS:  true-scale  normal  and  reverse  bitmaps  added 

generates  an  Expose  event,  which  will  then  cause  Label  to  redraw  the  widget  But  this 
causes  the  pixmap  to  flash  annoyingly  every  time  a  pixel  is  changed,  since  the  server  clears 
each  window  to  its  background  color  before  the  pixmap  is  redrawn.  If  you  would  like  to  see 
this  problem,  or  the  code  to  implement  this  approach,  compile  and  run  xbitmopd.  The  second 
method,  which  avoids  the  flashing  problem,  is  to  synthesize  an  Expose  event  (create  an 
XExposeEvent  structure  and  fill  it  with  values)  and  send  it  to  the  Label  widget  using 
XSendEvent.  This  is  a  bit  of  a  kludge  but  it  works. 

The  source  of  this  (surmountable)  problem  is  that  the  Label  widget  is  designed  for  static  pix- 
maps.  If  it  provided  a  public  function  called  XawLabelRedrawPixmap,  we  could  more 
cleanly  correct  the  flashing  bug.  Although  adding  this  function  to  the  widget  code  would  be 
easy,  we  could  no  longer  call  the  remaining  widget  class  Label.  We  would  be  creating  a  new 
widget  class.  (Some  widget  sets  do  in  fact  define  two  separate  widget  classes,  one  for  dis 
playing  static  pixmaps,  the  other  for  dynamic,  editable  pixmaps.) 

An  alternate  approach  is  to  create  Core  widgets  for  each  small  pixmap  and  draw  into  them 
from  the  application,  as  illustrated  in  Figure  4-5.  This  way  we  can  redraw  each  pixmap  with 
out  clearing  the  window  in  between  each  update,  eliminating  the  flash.  We  can  consider  this 
approach  because  these  small  pixmap  widgets  have  no  input  semantics  and  simple  output 
semantics  and  should  be  easy  to  implement 
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Figure  4-5.  Application  draws  into  Pixmap  and  copies  it  to  widget  window 

Three  new  routines  are  needed:  redraw_small_picture,  set_up_things,  and 
cell_toggled.  These  three  routines  are  primarily  composed  of  Xlib  calls  that  set  up  for 
and  perform  graphics.  The  redraw_small_picture  routine  copies  a  pixmap  into  a 
widget,  set_up_things  creates  the  pixmaps  and  the  GCs  needed  to  draw  into  these  pix- 
maps,  and  cell_toggled  is  a  callback  function  registered  with  the  BitmapEdit  widget 
that  updates  the  pixmaps  whenever  a  cell  is  toggled.  Code  is  also  added  to  main  to  create 
the  two  Core  widgets  and  give  them  translations  so  that  they  are  redrawn  on  Expose  events. 
We'll  show  these  routines  one  at  a  time.  Example  4-6  shows  the  improvements  to  the  main 
routine. 

Example  4-6.  xbitmapS:  implementing  small  pixmaps  by  drawing  into  Core  widgets 

main(argc,  argv) 
int  argc; 
char  *argv[] ; 
{ 

Widget  toplevel,  form,  buttonbox,  quit,  output; 

static  XtActionsRec  window_actions [ ]  =  { 
{ nredraw_small_picture",  redraw_small_picture} 

}; 

String  trans  =  "<Expose>:    redraw_small_picture () "; 

bigBitmap  =  XtCreateManagedWidget ("bigBitmap", 
bitmapEditWidgetClass,  form,  NULL,  0) ; 

XtAddCallback (bigBitmap,  XtNcallback,  cell_toggled,  NULL); 
XtAddActions (window  actions,  XtNumber (window  actions)); 


i   =    0; 
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Example  4-6.   xbitmapS:  implementing  small  pixmaps  by  drawing  into  Core  widgets   (con 
tinued) 


XtSetArg(args[i]  ,  XtNwidth,  pixmap_width_in_cells)  ; 
XtSetArg(args[i]  ,  XtNheight,  pixmap_height_in_cells)  ; 
XtSetArg(args[i]  ,  XtNtranslations, 

XtParseTranslationTable  (trans)  )  ;     i++; 
showNormalBitmap  =  XtCreateManagedWidget  ("showNormalBitmap", 

widgetClass,  buttonbox,  args,  i)  ; 

showReverseBitmap  =  XtCreateManagedWidget  ("showReverseBitmap", 
widgetClass,  buttonbox,  args,  i)  ; 

XtRealizeWidget  (toplevel)  ; 
XtMainLoop  {  )  ; 

II   } 

Core  widgets  are  created  using  the  class  pointer  widgetClass,  rather  than  core- 
widget  Class  as  you  might  have  expected.*  The  include  files  for  Core  (and  Composite 
and  Constraint)  are  included  by  <XlllIntrinsics.h>  and  therefore  don't  need  to  appear  in  the 
application. 

Note  that  the  size  of  the  Core  widget  must  be  set  before  the  Core  widgets  are  realized  (either 
in  the  application  or  in  the  application-defaults  file),  since  the  Core  widget  has  a  default  size 
of  zero  and  Xt  does  not  allow  widgets  with  a  size  of  zero.  Here  we  use  xt  Set  Arg  to  set  the 
size  in  the  argument  list  used  to  create  the  widgets.  The  same  argument  list  is  used  to  create 
both  widgets. 

The  main  routine  arranges  for  the  redraw_small_picture  routine  to  be  called  when 
ever  an  Expose  event  arrives  for  either  Core  widget,  and  registers  the  cell_toggled 
callback  with  the  BitmapEdit  widget  These  routines  depend  on  the  setup  performed  in 
set_up_things. 

4.3.1    Graphics  from  the  Application 

Drawing  in  the  X  Window  System  is  done  by  creating  a  graphics  context  (GC)  that  specifies 
such  things  as  colors  and  line  widths,  and  then  calling  a  drawing  routine  that  specifies  what 
shape  is  to  be  drawn.  These  two  steps  are  basic  to  X  and  required  in  programs  written  in  any 
language  with  or  without  a  toolkit.  For  example,  the  call  to  draw  a  line  specifies  only  the 
start  and  endpoints  of  the  line.  The  GC  specifies  everything  else  about  how  the  server  will 
actually  draw  this  line. 

A  GC  is  a  server-side  object  that  must  be  created  by  the  application.  The  purpose  of  the  GC 
is  to  cache  on  the  server  side  information  about  how  graphics  are  to  be  executed  by  the 
server,  so  that  this  information  doesn't  have  to  be  sent  over  the  network  with  every  graphics 
call.  If  X  did  not  have  GCs,  every  graphics  call  would  have  many  arguments  and  this  would 
waste  network  time  (and  be  annoying  to  program).  Instead,  you  create  a  small  number  of 
GCs  before  drawing  (in  the  startup  phase  of  the  application),  each  representing  a  particular 
color  or  line  style  you  will  need  to  draw  in  at  some  point,  and  then  specify  one  of  these  GCs 


*As  of  Release  4,  coreWidgetClass  will  also  woik. 
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in  each  call  to  draw.  For  example,  to  draw  text  and  be  able  to  highlight  it  at  will,  it  is  cus 
tomary  to  create  two  GCs,  one  for  drawing  in  white  on  black,  and  one  for  drawing  in  black 
on  white  (where  colors  can  be  substituted  for  black  and  white  on  color  screens). 

Once  created,  a  GC  is  referred  to  by  its  ID,  of  type  GC.  This  ID  is  specified  in  calls  to  draw 
using  that  GC. 

From  the  application,  the  Xlib  routine  XGreateGC  is  usually  used  to  create  GCs.  Xt  also 
provides  the  xtGetGC  routine  for  creating  GCs,  but  it  is  typically  used  only  inside  widget 
code  when  there  could  be  many  of  the  same  GCs  created.  XtGetGC  is  very  similar  to 
XGreateGC,  except  that  it  arranges  for  GCs  to  be  shared  among  widgets  (within  one  appli 
cation).  XtGetGC  will  be  described  in  Section  6.1. 

Xt  does  not  provide  drawing  calls  of  its  own.  You  must  call  Xlib  directly  to  draw.  An  Xlib 
drawing  routine  is  known  as  a  primitive.  Under  X,  text  is  drawn  by  a  graphics  primitive,  just 
as  lines,  arcs,  and  other  graphics  are  drawn. 

Colors  are  normally  specified  by  the  user  as  strings  such  as  "blue,"  but  the  X  server  under 
stands  colors  only  when  specified  as  numbers  called  pixel  values.  A  pixel  value  is  used  as  an 
index  to  a  lookup  table  called  a  colormap,  which  contains  values  for  the  RGB  (red-green- 
blue)  primaries  used  to  generate  colors  on  the  screen.  However,  a  particular  pixel  value  does 
not  necessarily  always  map  to  the  same  color,  even  when  run  twice  on  the  same  system, 
because  the  contents  of  the  colormap  are  configurable  on  most  color  systems.  The  wide  vari 
ation  of  graphics  hardware  that  X  supports  has  required  that  the  design  of  color  handling  in  X 
be  very  flexible  and  very  complex. 

Fortunately,  as  long  as  your  widget  or  application  requires  only  a  small  number  of  colors,  and 
you  do  not  particularly  care  whether  the  colors  you  get  are  exactly  the  colors  you  requested, 
Xt  provides  a  simplified  interface.  It  hides  the  actual  Xlib  calls  involved  in  the  Resource 
Manager's  converter  routines.  As  described  in  Chapter  3,  if  you  specify  application 
resources  for  colors  in  a  resource  list,  Xt  will  automatically  convert  color  names  specified  as 
resource  settings  into  pixel  values.  If  you  need  to  do  more  advanced  color  handling,  then  you 
will  need  to  make  Xlib  calls  yourself.  For  a  description  of  Xlib's  color  handling,  see  Chapter 
7,  Color  in  Volume  One,  Xlib  Programming  Manual. 

All  the  versions  of  xbitmap  so  far  in  this  chapter  work  either  in  color  or  monochrome,  since 
the  widgets  they  create  can  have  their  color  set  by  resources.  (They  default  to  black  and 
white,  even  on  a  color  screen.)  However,  to  support  color  in  the  small  pixmaps  we  are  creat 
ing  takes  more  work.  We  would  need  to  add  application  resources  to  get  the  pixel  values  that 
will  be  set  into  the  GCs  used  in  drawing,  as  described  in  Section  3.5. 

In  xbitmapS,  the  set_up_things  routine  is  responsible  for  creating  two  pixmaps  that  act 
as  drawing  surfaces,  and  two  GCs  that  will  be  used  to  draw  and  undraw  pixels  in  the  pix 
maps.  Whenever  the  Core  widgets  need  updating,  the  pixmaps  are  copied  into  the  widgets. 
This  is  only  one  possible  approach  to  adding  this  feature.  Another  is  to  draw  the  required 
points  directly  into  the  Core  widgets  each  time  they  need  updating,  keeping  a  record  of  the 
drawn  points  so  that  the  entire  widget  can  be  redrawn  in  case  of  exposure. 
set_up_things  is  shown  in  conjunction  with  the  next  version  of  xbitmap,  xbimap4,  at 
the  end  of  this  chapter. 
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Example  4-7  shows  the  cell_toggled  routine.  As  you  may  recall,  this  routine  is  a  call 
back  function  registered  with  the  BitmapEdit  widget,  to  be  called  whenever  a  cell  is  toggled. 

Example  4-7.  xbhmap3:  the  cell_toggled  routine 

/*  ARGSUSED  */ 

static  void 

cell_toggled(w,  unused,  info) 

Widget  w; 

caddr_t  unused;   /*  client_data  */ 

caddr_t  info;     /*  call_data  */ 

{ 

BitmapEditPointlnfo  *cur_info  =  (BitmapEditPointlnfo  *)  info; 

/* 

*  Note,  BitmapEditPointlnfo  is  defined  in  BitmapEdit. h 
*/ 

XDrawPoint (XtDisplay (w) ,  normal_bitmap,  ( (cur_info->mode 

==  UNDRAWN)  ?  draw_gc  :  undraw_gc) ,  cur_info->newx, 

cur_inf o->newy) ; 
XDrawPoint (XtDisplay (w) ,  reverse_bitmap,  ( (cur_info->mode 

==  UNDRAWN)  ?  undraw_gc  :  draw_gc) ,  cur_inf o->newx, 

cur_info->newy) ; 

redraw_small_picture (showNormalBitmap) ; 
redraw_small_picture (showReverseBitmap) ; 
} 

Note  that  BitmapEdit  passes  a  structure  called  BitmapEditPointlnfo  into  the  callback 
function  as  an  argument.  This  structure  is  defined  in  the  public  include  file,  BitmapEdit. h, 
and  it  provides  the  information  necessary  to  keep  the  small  bitmaps  displaying  the  same  pat 
tern  as  BitmapEdit.  The  fields  of  BitmapEditPointlnfo  are  the  mode  (whether  drawn 
or  undrawn)  and  the  coordinates  of  the  point  toggled.  The  cell_toggled  routine  draws 
points  into  the  pixmaps  according  to  the  information  passed  in,  and  then  calls 
redraw_small_picture  to  copy  the  pixmaps  into  each  Core  widget 

The  first  line  of  cell_toggled  casts  the  generic  pointer  info  into  the  structure  type 
defined  by  BitmapEdit,  BitmapEditPointlnfo.  This  can  also  be  done  (perhaps  more 
clearly)  by  declaring  the  info  argument  as  type  BitmapEditPointlnfo  in  the  first 
place.  However,  some  programmers  have  a  preference  for  using  a  cast. 

The  redraw_small_j>icture  routine  is  shown  in  Example  4-8. 

Example  4-8.  xbitmapS:  the  redraw_small_picture  routine 

static   void 

redraw_small_picture (w) 
Widget  w; 
{ 

Pixmap  pixmap; 

if  (w  ==  showNormalBitmap) 

pixmap  =  normal_bitmap; 
else 

pixmap  =  reverse_bitmap; 

/* 

*  Note  that  DefaultGCOfScreen  is  one  plane  on  monochrome 
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Example  4-8.  xbitmapS:  the  redraw_small_picture  routine  (continued) 

*  screens,  but  multiple  planes  on  color  screens.   The  GCs 

*  created  in  set_up_things  are  always  single  plane. 
*/ 

if  (Def aultDepthOf Screen (XtScreen (w) )  ==  1) 

XCopyArea(XtDisplay (w) ,  pixmap,  XtWindow(w), 
Def aultGCOf Screen (XtScreen (w) ),  0,  0, 

pixmap_width_in_cells,  pixmap_height_in_cells,  0,  0) ; 
else 

XCopyPlane (XtDisplay (w) ,  pixmap,  XtWindow(w), 
DefaultGCOf Screen (XtScreen (w) ),  0,  0, 

pixmap_width_in_cells,  pixmap_height_in_cells,  0,  0,  1) 
} 

This  routine  is  called  from  cell_toggled  and  by  Xt  in  response  to  Expose  events 
because  we  registered  it  as  an  action  and  specified  it  in  the  translation  table  resource  of  each 
of  the  Core  widgets.  The  use  of  one  of  two  Xlib  routines,  depending  on  the  depth  of  the 
screen,  is  an  optimization.  XCopyArea  is  faster,  but  can  be  used  for  this  job  only  on  mono 
chrome  displays,  because  the  pixmaps  are  one  plane  deep  on  all  displays  and  must  be 
translated  into  multiple  planes  with  XCopyPlane  on  color  displays. 

See  Volume  One,  Xlib  Programming  Manual,  for  details. 

4.3.2   Writing  a  Bitmap  File 

Once  we  have  pixmaps  in  our  application  that  contain  the  current  bitmap,  it  is  a  trivial  matter 
to  change  the  printout  callback  function  to  write  a  bitmap  file  instead  of  just  printing  an 
array  of  1's  and  O's  to  the  standard  output  This  is  easy  because  there  is  an  Xlib  function, 
XWriteBitmapFile,  that  writes  the  contents  of  a  single-plane  pixmap  into  a  file. 
Example  4-9  shows  the  code  that  gets  a  filename  from  the  command  line  and  then  writes  the 
bitmap  file. 

Example  4-9.  xbitmap3:  writing  a  bitmap  file 

String  filename;  /*  filename  to  read  and  write  */ 

/*  ARGSUSED  */ 

static  void 

printout (widget,  client_data,  call_data) 

Widget  widget; 

caddr_t  client_data,  call_data;  /*  unused  */ 

{ 

XWriteBitmapFile (XtDisplay (widget) ,  filename,  normal_bitmap, 

pixmap_width_in_cells,  pixmap_height_in_cells,  0,  0); 
} 

main (argc,  argv) 
int  argc; 
char  *argv [ ] ; 


/*  Xtlnitialize  */ 
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Example  4-9.  xbitmapS:  writing  a  bitmap  file  (continued) 


if  (argv[l]  !=  NULL) 

filename  =  argv[l]; 
else  { 

fprintf (stderr,  "xbitmap:  must  specify  filename \ 
on  command  line.\n"); 

exit  (1) ; 


Contrast  this  version  of  printout  to  the  one  shown  in  Example  4-1. 

Note  that  reading  a  bitmap  file  is  not  difficult  either,  but  we  will  not  take  the  space  to 
describe  it  If  you  are  curious,  the  complete  code  for  xbitmapS,  which  both  reads  and  writes 
bitmap  files,  is  shown  in  Appendix  F,  The  xbitmap  Application. 


4.4  xbitmap4:  Bitmap  Editor  Without  a  BitmapEdit  Widget 

Many  applications  have  at  least  one  window  that  has  certain  characteristics  not  available  in 
any  existing  widget  class  in  any  widget  set.  The  small  bitmaps  added  in  the  last  section  pro 
vided  a  simple  example  of  making  a  custom  window  by  creating  a  Core  widget  and  drawing 
into  it  from  the  application. 

Until  you  have  experience  working  with  widget  code,  it  may  be  easier  to  prototype  the  "cus 
tom  window"  for  your  application  by  adding  to  a  Core  widget  using  just  the  techniques 
described  so  far  in  this  book.  Once  this  code  is  working,  and  you  have  read  Chapters  5  and  6, 
you  can  easily  move  the  code  into  a  widget  when  you  want  to  package  it  or  take  advantage  of 
any  of  the  features  of  Xt  that  are  inaccessible  from  the  application. 

The  code  for  the  BitmapEdit  widget  was  originally  written  in  an  application,  and  later  moved 
into  a  widget.  In  this  section  we  describe  this  original  application,  a  version  of  xbitmap  that 
works  just  like  xbitmapl  but  without  using  the  BitmapEdit  widget  This  example  is  a  culmi 
nation  of  many  of  the  techniques  described  so  far  in  this  book.  In  addition,  you  will  be  see 
ing  this  same  code  inside  the  BitmapEdit  widget  in  Chapters  5  and  6,  and  it  should  be  easier 
to  understand  the  additional  widget  code  when  you  have  already  seen  the  functional  code 
described  in  a  familiar  setting. 

This  example  takes  advantage  of  application  resources  to  set  the  configurable  parameters  of 
the  bitmap  code.  The  code  that  sets  up  the  application  resources  was  described  in  Section 
3.5.  When  moving  the  code  into  a  widget  framework,  the  same  resource  list  will  be  used  ver 
batim.  The  example  also  provides  command-line  options  to  set  the  important  parameters  of 
the  bitmap  code.  The  code  for  processing  these  options  was  described  in  Section  3.6.  The 
code  is  the  same  whether  it  is  used  for  setting  application  resources  or  widget  resources, 
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except  that  no  call  equivalent  to  XtGetApplicationResources  is  necessary  in  a 
widget 

The  exposure  strategy  used  for  the  bitmap  editor  is  the  same  as  for  the  small  bitmaps  in  the 
previous  section.  The  application  creates  a  large  pixmap  of  depth  one  that  stores  the  current 
image  of  the  bitmap  being  edited.  Whenever  the  screen  needs  updating,  the  applicable  part 
of  the  pixmap  is  copied  to  the  Core  widget  in  the  redraw_jpicture  routine.  Since  this 
pixmap  is  much  bigger  than  the  ones  in  the  last  section,  it  is  an  important  optimization  that 
only  the  required  parts  of  the  pixmap  are  copied.  (This  is  not  the  only  possible  exposure 
strategy.  This  particular  strategy  has  very  low  network  load,  but  uses  a  relatively  large 
amount  of  server  memory.  For  this  reason  it  is  not  ideal  for  PC  servers.) 

The  set_up_things  routine  creates  the  pixmap,  draws  a  grid  into  it  that  will  persist  for 
the  life  of  the  application,  and  creates  three  GCs.  One  GC  is  for  copying  from  the  pixmap  to 
the  window,  and  two  are  for  drawing  and  undrawing  cells  in  the  pixmap.  The  btn_event 
routine  draws  and  undraws  cells  in  the  pixmap  according  to  pointer  clicks  and  drags,  and 
calls  redraw_j>icture  to  update  the  Core  widget  display. 

redraw_picture  is  called  both  from  the  application  and  from  Xt.  This  is  a  common 
trick  used  to  reduce  the  duplication  of  drawing  code.  Since  redraw_picture  is  an 
action,  it  has  an  event  argument  that  is  used  by  Xt  to  pass  in  the  Expose  event  describing 
the  area  exposed.  This  application  also  uses  this  argument  by  constructing  a  fake  event  to 
pass  in  information  about  which  part  of  the  widget  to  draw. 

The  application  adds  actions  and  sets  the  xtNtranslations  resource  of  the  Core  widget 
so  that  Xt  calls  the  application  routine  redraw_jpicture  whenever  Expose  events 
arrive,  and  calls  btn_event  when  ButtonPress  orMotionNotify  events  arrive. 

Example  4-10  shows  the  complete  code  for  xbitmap4 .  You  have  seen  all  the  techniques  here 
in  various  examples  before.  You  should  work  through  the  code  and  make  sure  you  under 
stand  the  purpose  of  each  section.  However,  don't  worry  about  the  details  of  the  Xlib  calls, 
since  they  are  specific  to  this  application. 

Example  4-10.  xbitmap4:  implementing  the  bitmap  editor  from  the  application 

/* 

*  xbitmap4.c 
*/ 

tinclude  <Xll/Intrinsic.h> 
tinclude  <Xll/StringDef s .h> 

tifdef  X11R3 

tinclude  <Xll/VPaned.h> 

tinclude  <Xll/Box.h> 

tinclude  <X11 /Command. h> 

telse  /*  R4  or  later  */ 

tinclude  <Xll/Xaw/Paned.h> 

tinclude  <Xll/Xaw/Box.h> 

tinclude  <Xll/Xaw/Command.h> 

tendif  /*  X11R3  */ 

tinclude  <stdio.h> 

/  * 

*  The  following  could  be  placed  in  an  "xbitmap.h"  file. 
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Example  4-10.  xbitmap4:  implementing  the  bitmap  editor  from  the  application  (continued) 

*/ 

#define  XtNdebug  "debug" 
tdefine  XtCDebug  "Debug" 

tdefine  XtNpixmapWidthlnCells  "pixmapWidthlnCells" 
#define  XtCPixmapWidthlnCells  "PixmapWidthlnCells" 
tdefine  XtNpixmapHeightlnCells  "pixmapHeightlnCells" 
tdefine  XtCPixmapHeightlnCells  "PixmapHeightlnCells" 
tdefine  XtNcellSizelnPixels  "cellSizelnPixels" 
tdefine  XtCCellSizelnPixels  "CellSizelnPixels" 

tdefine  DRAWN  1 
tdefine  UNDRAWN  0 

tdefine  DRAW  1 
tdefine  UNDRAW  0 

tdefine  MAXLINES   1000 

tdefine  MINBITMAPWIDTH   1 
tdefine  MAXBITMAPWIDTH   1000 
tdefine  MINCELLSIZE   4 
tdefine  MAXCELLSIZE   100 

tdefine  DEFAULTWIDTH  300 
tdefine  DEFAULTHEIGHT  300 

tdefine  SCROLLBARWIDTH  15 

Pixmap  big_j3icture; 

GC  draw_gc,  undraw_gc;/*  drawing  into  the  big_picture, 1-bit  deep  */ 

GC  copy_gc;        /*  copying  from  pixmap  into  window, screen  depth  */ 

Widget  bitmap;     /*  this  is  the  drawing  surface  */ 

char  *cell;        /*  this  is  the  array  for  printing  output  and  */ 

int  cur_x,  cur_y;  /*  keeping  track  of  cells  drawn  */ 

int  pixmap_width_in_pixels,  pixmap_height_in_pixels; 

/*  data  structure  for  application  resources  */ 
typedef  struct  { 

Pixel  copy_fg; 

Pixel  copy_bg; 

int  pixmap_width_in_cells; 

int  pixmap_height__in_cells; 

int  cell_size_in_pixels; 

Boolean  debug; 
}  AppData,  *AppDataPtr; 

AppData  app_data; 

/*  resource  list  */ 

static  XtResource  resources []  =  { 

( 

XtNforeground, 

XtCForeground, 

XtRPixel, 

sizeof (Pixel) , 

XtOf f set (AppDataPtr,  copy_fg) , 

XtRString, 

XtDefaultForeground 
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Example  4-10.  xbitmap4:  implementing  the  bitmap  editor  from  the  application  (continued) 

XtNbackground, 

XtCBackground, 

XtRPixel, 

sizeof (Pixel) , 

XtOf fset (AppDataPtr,  copy_bg) , 

XtRString, 

Xt Default Background 


XtNpixmapWidthlnCells, 

XtCPixmapWidthlnCells, 

XtRInt, 

sizeof  (int)  , 

XtOf  f  set  {AppDataPtr,  pixmap_width_in_cells)  , 

XtR  Immediate, 

(caddr_t)  32, 


XtNpixmapHeightlnCells, 
XtCPixmapHeightlnCells, 
XtRInt, 
sizeof  (int)  , 

XtOf  fset  (AppDataPtr,  pixmap_height_in_cells)  , 
XtR  Immediate, 
(caddr_t)  32, 


XtNcellSizelnPixels, 

XtCCellSizelnPixels, 

XtRInt, 

sizeof  (int)  , 

XtOf  fset  (AppDataPtr,  cell_size_in_pixels)  , 

XtRImmediate, 

(caddr_t)  30, 


XtNdebug, 

XtCDebug, 

XtRBoolean, 

sizeof  (Boolean)  , 

XtOf  fset  (AppDataPtr,  debug)  , 

XtRImmediate, 

(caddr_t)  FALSE, 


/*  Command-line  options  table  */ 

static  XrmOptionDescRec  options []  =  { 

{"-pw",  "*pixmapWidthInCells",  XrmoptionSepArg,  NULL}, 

{"-pixmapwidth",   "*pixmapWidthInCells",  XrmoptionSepArg,  NULL}, 

{"— ph",  "*pixmapHeightInCells",  XrmoptionSepArg,  NULL}, 

{ "-pixmapheight",  "*pixmapHeightInCells",  XrmoptionSepArg,  NULL}, 

{ "-cellsize",      "*cellSizeInPixels",  XrmoptionSepArg,  NULL}, 

{"-fg",  "*foreground",  XrmoptionSepArg,  NULL}, 

{"-foreground",    "*foreground",  XrmoptionSepArg,  NULL}, 

{"-debug",         "*debug",  XrmoptionNoArg,  "True"} 


126  X  Toolkit  Intrinsics  Programming  Manual 


Example  4-10.  xbitmap4:  implementing  the  bitmap  editor  from  the  application  (continued) 

>; 

/*  callback  function  to  print  cell  array  to  stdout  */ 
/*  ARGSUSED  */ 
static  void 
printout () 


int  x,  y; 

putchar  ( ' \n'  )  ; 
for  (y  =  0;  y 


app_data.pixmap_height_in_cells; 


for  (x  =  0;  x  <  app_data .pixmap_width_in_cells;  x++) 

putchar (cell [x  +  y  *  app_data.pixmap_width_in_cells] 

?  '  1 '  :  '  0 ' )  ; 
putchar (' \n' ) ; 

putchar (' \n' ) ; 


static  void  RedrawPicture  ()  ,  DrawCellO,  UndrawCell  ()  , 
ToggleCell  ()  ,  DrawPixmaps  ()  ; 

static  void  Syntax  (argc,  argv) 
int  argc; 
char  *  argv  [  ]  ; 
{ 

int  i; 

static  int  errs  =  False; 

/*  first  argument  is  program  name  -  skip  that  */ 
for  (1=1;  i  <  argc;  i++)  { 
if  (!errs++)  /*  do  first  time  through  */ 

fprintf  (stderr,  "xbitmap4  :  command  line  optionX 

not  understood:  \n")  ; 
fprintf  (stderr,  "option:  %s\n",  argv[i]); 


fprintf  (stderr,  "xbitmap  understands  all  standard  Xt\ 

command  line  options  .  \n")  ; 


fprintf (stderr,  "Additional  options 

fprintf (stderr,  "Option 

fprintf (stderr,  "-pw 

fprintf (stderr,  "-pixmapwidth 

fprintf (stderr,  "-ph 

fprintf (stderr,  "-pixmapheight 

fprintf (stderr,  "-cellsize 

fprintf (stderr,  "-fg 

fprintf (stderr,  "-foreground 

fprintf (stderr,  "-debug 


are  as  follows : \n") ; 

Valid  RangeXn") ; 

2  to  lOOOXn") 

2  to  1000\n") 

2  to  lOOOXn") 

2  to  lOOOXn") 

4  to  lOOXn") ; 

color  nameXn"); 

color  nameXn") ; 

no  value  necessaryXn") 


main (argc,  argv) 
int  argc; 
char  *argv [ ] ; 
{ 

int  i; 

Arg  args [5] ; 

Widget  topLevel,  vpane,  buttonbox,  guit,  output 
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Example  4-10.  xb'rtmap4:  implementing  the  bitmap  editor  from  the  application  (continued) 

/*    translation   table    for   bitmap   core    widget    */ 

String   trans   = 

"<Expose>:  RedrawPicture ()  \n\ 

<BtnlDown>:  DrawCellO  \n\ 

<Btn2Down>:  UndrawCellO  \n\ 

<Btn3Down>:  ToggleCell ( )  \n\ 

<BtnlMotion>:  DrawCellO  \n\ 

<Btn2Motion>:  UndrawCellO  \n\ 

<Btn3Motion>:  ToggleCell ()"; 

static   XtActionsRec   window_actions [ ]    =    { 

{ "RedrawPicture",  RedrawPicture } , 

{"DrawCell",  DrawCell}, 

{"UndrawCell",    UndrawCell}, 

{"ToggleCell11,    ToggleCell}, 
}; 

topLevel  =  Xtlnitialize {  argv[0], 
"XB it map 4 ", 
options, 

XtNumber (options) , 
&argc, 
argv) ; 

/*  Xtlnitialize  leaves  program  name  in  args  */ 
if  (argc  >  1) 

Syntax (argc,  argv); 

XtGetApplicationRe sources (topLevel, 
&app_data, 
resources, 

XtNumber (resources) , 
NULL, 
0); 

/* 

*  We  must  check  the  application  resource  values  here. 

*  Otherwise,  user  could  supply  out  of  range  values 

*  and  crash  program.   Conversion  routines  do  this 

*  automatically,  so  colors  are  already  checked. 
*/ 

if  ( (app_data.pixmap_width_in_cells  >  MAXBITMAPWIDTH)  || 

(app_data.pixmap_width_in_cells  <  MINBITMAPWIDTH)  | | 
(app_data.pixmap_height_in_cells  >  MAXBITMAPWIDTH)  | | 
(app_data.pixmap_height_in_cells  <  MINBITMAPWIDTH))  { 
fprintf (stderr,  "xbitmap:  error  in  resource  settings:", 
"dimension  must  be  between  %d  and  %d  cells\n", 
MINBITMAPWIDTH,  MAXBITMAPWIDTH) ; 
exit  (1)  ; 
} 
if  ( (app_data.cell_size_in_pixels  <  MINCELLSIZE)  I  I 

(app_data.cell_size_in_pixels  >  MAXCELLSIZE) )  { 
fprintf (stderr,  "xbitmap:  error  in  resource  settings:", 
"cell  size  must  be  between  %d  and  %d  pixels\n", 
MINCELLSIZE,  MAXCELLSIZE); 
exit  (1)  ; 
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Example  4-1 0.  xbitmap4:  implementing  the  bitmap  editor  from  the  application  (continued) 
/*    begin    application    code    */ 
set_up_things (topLevel) ; 

cell  =  XtCalloc (app_data.pixmap_width_in_cells  * 

app_data.pixmap_height_in_cells,  sizeof (char) ) ; 

if  (app_data .debug) 

fprintf (stderr,  "xbitmap:  pixmap\ 
dimensions  are  %d  by  %d\n", 
app_data .pixmap_width_in_cells, 
app_data.pixmap_height_in_cells) ; 

i  =  0; 

XtSetArg(args [i] ,  XtNwidth,  (pixmap_width_in_pixels  >  300) 

?  (300  +  SCROLLBARWIDTH  +  15)  :  (pixmap_width_in_pixels 

+  SCROLLBARWIDTH  +  15));    i++; 

/*  following  line  is  a  kludge  */ 
XtSetArg(args[i] ,  XtNheight,  15);    i  +  +  ; 

tifdef  X11R3 

vpane  =  XtCreateManagedWidget ("vpane",  vPanedWidgetClass, 

topLevel,  args,  i) ; 
#else  /*  R4  or  later  */ 

vpane  =  XtCreateManagedWidget ("vpane",  panedWidgetClass, 

topLevel,  args,  i) ; 
tendif  /*  X11R3  */ 

buttonbox  =  XtCreateManagedWidget ("buttonbox",  boxWidgetClass, 
vpane,  NULL,  0) ; 

output  =  XtCreateManagedWidget ("output",  commandWidgetClass, 
buttonbox,  NULL,  0) ; 

XtAddCallback (output,  XtNcallback,  printout,  NULL); 

quit  =  XtCreateManagedWidget ("quit",  commandWidgetClass, 
buttonbox,  NULL,  0); 

XtAddCallback (quit,  XtNcallback,  exit,  NULL) ; 

1  =  0; 

XtSetArg (args [i] ,  XtNtranslations, 

XtParseTranslationTable (trans) ) ;   i++; 
XtSetArg (args [ i] ,  XtNwidth, 

(pixmap_width_in_pixels  >  300)  ?  300  : 

pixmap_width_in_pixels) ;   i++; 
XtSetArg (args [i] ,  XtNheight, 

(pixmap_height_in_pixels  >  300)  ?  300  : 

pixmap_height_in_pixels) ;   i++; 
bitmap  =  XtCreateManagedWidget ("bitmap",  widgetClass, 

vpane,  args,  i) ; 

XtAddActions  (wi-ndow_actions,  XtNumber  (window_actions)  )  ; 
XtRealizeWidget (topLevel) ; 

XtMainLoop  () ; 
} 

set_up_things (w) 


An  Example  Application 


Example  4-10.  xbitmap4:  implementing  the  bitmap  editor  from  the  application  (continued) 

Widget  w; 
{ 

XGCValues  values; 

int  x,  y; 

XSegment  segment [MAXLINES] ; 

int  n_horiz_segments,  n_vert_segments; 

pixmap_width_in_pixels  =  app_data.pixmap_width_in_cells  * 

app_data .cell_size_in_pixels; 
pixmap_height_in_pixels  =  app_data.pixmap_height_in_cells  * 

app_data . cell_size_in_pixels; 

big_picture  =  XCreatePixmap (XtDisplay (w) , 
RootWindowOf Screen (XtScreen (w) ) , 
pixmap_width_in_pixels,  pixmap_height_in_pixels,  1); 

values . foreground  =  1; 

values .background  =  0; 

values. dashes  =1; 

values .dash_off set  =  0; 

values . line_style  =  LineOnOf fDash; 

draw_gc  =  XCreateGC (XtDisplay (w) ,  big_picture, 

GCForeground  |  GCBackground  |  GCDashOffset  | 
GCDashList  |  GCLineStyle,  Svalues) ; 

values. foreground  =  0; 
values. background  =  1; 
undraw_gc  =  XCreateGC (XtDisplay (w) ,  big_picture, 

GCForeground  I  GCBackground  I  GCDashOffset  | 

GCDashList  |  GCLineStyle,  Svalues) ; 

values. foreground  =  app_data.copy_fg; 

values. background  =  app_data.copy_bg; 

copy_gc  =  XCreateGC (XtDisplay (w) , 

RootWindowOf Screen (XtScreen (w) ) , 
GCForeground  |  GCBackground,  & values) ; 

/*  draw  permanent  grid  into  pixmap  */ 

n_horiz_segments  =  app_data .pixmap_height_in_cells  +  1; 

n_vert_segments  =  app_data .pixmap_width_in_cells  +  1; 

for  (x  =  0;  x  <  n_horiz_segments;  x  +=  1)  { 

segment [x] ,xl  =  0; 

segment [x] .x2  =  pixmap_width_in_pixels; 

segment [x] .yl  =  app_data .cell_size_in_pixels  *  x; 

segment [x] .y2  =  app_data .cell_size_in_pixels  *  x; 
} 

/*  drawn  only  once  into  pixmap  */ 

XDrawSegments (XtDisplay (w) ,  big^picture,  draw_gc,  segment, 
n_horiz_segments) ; 

for  (y  =  0;  y  <  n_vert_segments;  y  +=  1)  { 

segment [y] .xl  =  y  *  app_data.cell_size_in_pixels; 
segment  [y]  .x2  =  y  *  app_data.cell_size_in_jpixels; 
segment [y] .yl  =  0; 
segment [y] .y2  =  pixmap_height_in_pixels; 
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Example  4-10.  xbitmap4:  implementing  the  bitmap  editor  from  the  application  (continued) 

/*  drawn  only  once  into  pixmap  */ 

XDrawSegments (XtDisplay (w) ,  big_picture,  draw_gc,  segment, 
n_vert_segments) ; 

} 

/*  Action  */ 
static  void 

RedrawPicture (w,  event) 
Widget  w; 

XExposeEvent  *event; 
{ 

register  int  x,  y; 

unsigned  int  width,  height; 

if  (event)  {          /*  drawing  because  of  expose  or  button  press  */ 

x  =  event->x; 

y  =  event->y; 

width  =  event->width; 

height  =   event->height; 
} 
else  {  /*  drawing  because  of  scrolling  */ 

x  =  0; 

y  -  0; 

width  =   10000;   /*  always  the  whole  window!  */ 

height  =   10000; 
} 

if  (Def aultDepthOf Screen (XtScreen (w) )  =  =  1) 

XCopyArea (XtDisplay (w) ,  big_picture,  .  XtWindow (w)  , 
copy_gc,  x  +  cur_x, 
y  +  cur_y,  width,  height,  x,  y) ; 
else 

XCopyPlane (XtDisplay (w) ,  big_picture,  XtWindow (w), 
copy_gc,  x  +  cur_x, 

y  +  cur_y,  width,  height,  x,  y,  1); 
} 

/*  Action  */ 
static  void 
DrawCell (w,  event) 
Widget  w; 

XButtonEvent  *event; 
{ 

DrawPixmaps (draw_gc,  DRAW,  w,  event); 
} 

/*  Action  */ 
static  void 
UndrawCell (w,  event) 
Widget  w; 

XButtonEvent  *event; 
{ 

DrawPixmaps (undraw_gc,  UNDRAW,  w,  event); 
} 

/*  Action  */ 
static  void 
ToggleCell (w,  event) 
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Example  4-1  0.  xbitmap4:  implementing  the  bitmap  editor  from  the  application  (continued) 

Widget  w; 

XButtonEvent  *event; 
{ 

static  int  oldx  =  -1,  oldy  =  -1; 

GC  gc; 

int  mode; 

int  newx  =  (cur_x  4-  event->x)  /  app_data  .cell_size_in_pixels; 

int  newy  =  (cur_y  +  event->y)  /  app_data  .cell_size_in_pixels; 

if  ((mode  =  cell  [newx  +  newy  *  app_data  .pixmap_width_in_cells]  ) 
==  DRAWN)  { 

gc  =  undraw_gc; 

mode  -  UNDRAW; 
} 
else  { 

gc  =  draw_gc; 

mode  =  DRAW; 


if  (oldx  !=  newx  I  I  oldy  1=  newy)  { 
oldx  =  newx; 
oldy  =  newy; 
DrawPixmaps  (gc,  mode,  w,  event); 


/*  Private  Function  */ 

static  void 

DrawPixmaps (gc,  mode,  w,  event) 

GC  gc; 

int  mode; 

Widget  w; 

XButtonEvent  *event; 

int  newx  =  (cur_x  +  event->x)  /  app_data .cell_size_in_pixels; 
int  newy  =  (cur_y  +  event->y)  /  app_data .cell_size_in_pixels; 
XExposeEvent  fake_event; 

/*  if  already  done,  return  */ 

if  (cell [newx  +  newy  *  app_data .pixmap_width_in_cells]  ==  mode) 
return; 

XFillRectangle (XtDisplay (w) ,  big_picture,  gc, 
app_data . cell_size_in_pixels*newx  +  2, 
app_data .cell_size_in_pixels*newy  +2, 
(unsigned  int) app_data .cell_size_in_pixels  -  3, 
(unsigned  int ) app_data .cell_size_in_pixels  -3); 

cell [newx  +  newy  *  app_data .pixmap_width_in_cells]  =  mode; 

fake_event.x  =  app_data . cell_size_in_pixels  *  newx  -  cur_x; 
fake_event.y  =  app_data . cell_size_in_pixels  *  newy  -  cur_y; 
fake_event .width  =  app_data . cell_size_in_pixels; 
fake_event .height  =  app_data .cell_size_in_pixels; 

RedrawPicture (bitmap,  Sfake  event); 
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Inside  a  Widget 


This  chapter  describes  the  code  inside  a  basic  widget.  Much  of  this  code  is 
common  to  all  widgets.  You  can  think  of  it  as  a  framework  that  Xt  uses  to 
implement  a  widget's  features.  After  reading  this  chapter,  you  should  under 
stand  the  procedure  for  creating  your  own  widget  around  this  framework. 

In  This  Chapter: 

Widget  Source  File  Organization 135 

The  Private  Header  File— B  it  map  Ed  it  P.  h  136 

Parts  and  Records 137 

Class  Part  and  Class  Record 138 

Instance  Part  and  Instance  Record 139 

The  Widget  Source  File — BitmapEdit.c 141 

Obligatory  Include  Files 141 

Defining  the  Resource  List 143 

The  Translation  Table  and  Actions  Table 145 

Declaring  Methods 147 

Initializing  the  Class  Record 148 

The  Core  Class  Part  148 

Initializing  the  Core  Methods 151 

Description  of  Core  Methods 153 

Packaging  the  Class  Record  for  Application  Use 155 

A  Sample  Method  155 

The  Public  Header  File— BitmapEdit.h 158 

The  Process  of  Widget  Writing 160 

Summary  of  Conventions 162 


5 
Inside  a  Widget 


This  chapter  reveals  the  framework  of  code  common  to  all  widgets.  As  an  example,  it 
describes  the  code  for  the  BitmapEdit  widget  that  was  used  in  versions  of  the  xbitmap  appli 
cations  early  in  Chapter  4,  An  Example  Application.  Later  examples  in  that  chapter  described 
how  to  implement  the  bitmap  editor  without  a  BitmapEdit  widget.  Therefore,  you  have 
already  seen  the  code  that  is  specific  to  this  widget,  and  can  concentrate  on  the  framework 
and  how  to  place  widget-specific  code  within  this  framework. 

Placing  specialized  user-interface  code  into  a  widget  has  several  advantages.  For  one,  the 
widget  becomes  a  self-contained  module  that  can  be  modified  and  documented  separately 
and  used  in  other  programs.  Second,  the  code  will  take  advantage  of  Xt's  automatic  dis 
patching  of  events  to  widgets,  and  several  other  features  that  you  can't  use  from  the  applica 
tion.  Finally,  it  is  a  general  premise  of  Xt  that  application  code  should  be  separated  as  much 
as  possible  from  user-interface  code. 

It  is  important  to  remember  that  widget  classes  are  never  written  from  scratch.  People 
always  start  from  template  files  that  contain  the  framework  for  a  widget  without  the  specific 
code,  or  even  better,  when  possible,  from  an  existing  widget  that  has  some  similar  character 
istics. 


5.1  Widget  Source  File  Organization 

A  widget  is  implemented  in  two  include  files  and  an  executable  code  file.  Each  of  these  files 
contains  specific  elements.  The  names  of  these  files  are  derived  from  the  name  of  the  widget 
class,  which  in  this  case  is  BitmapEdit: 

•  The  private  header  file,  BitmapEditP.h,  defines  the  widget's  class  and  instance  structures, 
including  pointers  to  the  widget's  methods. 

•  The  implementation  file,  BitmapEdit.c,  contains  the  actual  executable  code  for  the 
widget,  including  the  widget's  methods  and  actions. 

•  The  public  header  file,  BitmapEdit.h,  contains  declarations  needed  by  the  application  to 
use  the  widget 
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The  final  P  in  the  include  file  name  stands  for  Private.  Only  BitmapEdit.c  and  any  modules 
that  implement  subclasses  of  BitmapEdit  should  include  BitmapEditP .h.  If  an  application 
includes  this  file  and  references  any  of  its  contents,  it  is  breaking  the  rules  of  encapsulation, 
and  changes  to  this  widget  might  affect  the  application. 

An  application  program  that  uses  a  widget  includes  only  BitmapEdit.h. 

The  implementation  filenames  (and  all  the  filenames  used  by  your  application,  for  that  mat 
ter)  should  have  12  or  fewer  characters  or  less  so  that  the  code  can  be  copied  easily  to  some 
System  V  systems.* 

The  next  three  major  sections  describe  the  contents  of  the  three  files  that  make  up  a  widget. 
These  files  are  treated  in  the  order  shown  in  the  above  list  because  they  are  generally  devel 
oped  in  this  order. 


5.2  The  Private  Header  File— BitmapEditP.h 

Xt  implements  classes  and  instances  with  two  structures,  the  class  structure  and  the  instance 
structure.  By  definition  of  C  structures,  the  fields  in  both  structures  are  fixed  at  compile  time. 
Both  of  these  structures  are  defined  in  the  private  include  file  for  the  class,  in  this  case 
BitmapEditP.h. 

There  is  only  one  copy  of  the  class  structure  in  the  running  application,  which  all  instances 
share.  But  each  instance  has  its  own  copy  of  the  instance  structure,  whose  fields  are  set  by 
the  resource  database  as  the  instance  is  created.  Fields  in  the  instance  structure  can  also  be 
set  by  Xt  SetValues  or  read  by  XtGetValues. 

The  class  structure's  fields  contain  pointers  to  methods  and  pieces  of  data  that  control  how  Xt 
handles  instances  of  this  class. 

The  instance  structure  carries  a  complete  widget  state,  including  everything  that  can  be  dif 
ferent  between  one  instance  and  the  next.  For  example,  the  instance  structure  of  the  Core 
class,  which  every  widget  inherits,  has  fields  for  x,  y,  width,  and  height  values,  which 
correspond  to  the  size  of  the  widget  and  its  location  relative  to  the  top-left  corner  of  its  par 
ent.  These  particular  fields  are  public;  they  can  be  set  from  the  resource  database  or  with 
xtSetValues,  and  their  values  can  be  read  with  XtGetValues.  Other  instance  struc 
ture  fields  are  private,  and  are  used  only  for  convenience  to  make  data  globally  available 
within  the  widget 

Actually,  the  instance  structure  is  not  global  in  the  normal  C  sense.  When  Xt  invokes  a 
method,  it  passes  the  method  a  pointer  to  the  widget  instance  structure.  Methods  do  their 
work  by  using  the  public  fields  and  changing  the  private  fields  in  this  instance  structure.  For 
example,  a  method  that  draws  in  the  window  can  get  the  window's  dimensions  directly  from 


*  These  systems  have  a  14-character  filename  limit;  the  12-character  limit  allows  files  to  be  placed  under  source  con 
trol  or  compressed.  The  X  Consortium  keeps  all  filenames  to  a  maximum  of  12  characters.  That  limits  the  actual 
class  name  to  9  characters,  to  leave  room  for  the  P.h  suffix.  If  the  widget  class  name  is  longer  than  9  characters,  it  is 
truncated  in  the  filename.  For  example,  the  private  include  file  for  the  Constraint  class  is  Constrain?  h  (without  the 
final  t);  BitmapEditP  .h  is  BitmapEdiP  .h  in  our  example  code. 
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the  widget  instance  structure.  When  action  functions  are  called,  they  also  are  passed  a 
pointer  to  the  instance  structure.  Therefore,  the  fields  inside  the  instance  structure  are  avail 
able  just  about  everywhere  in  the  widget  code. 


5.2.1    Parts  and  Records 

The  organization  of  both  class  and  instance  structures  is  determined  by  the  hierarchy  of 
widget  classes  from  which  the  current  widget  class  is  derived.  For  example,  in  the  code  for 
the  BitmapEdit  widget  whose  class  hierarchy  is  shown  in  Figure  5-1,  the  class  structure 
begins  with  the  class  fields  defined  by  the  Core  class,  followed  by  the  class  fields  defined  by 
BitmapEdit. 


Class  hierarchy 


Core 


BitmapEdit 


i  Composite 

I 

•  Constraint 


Figure  5-1.  The  class  hierarchy  of  the  BitmapEdit  widget  (with  other  classes  shown  dotted) 


Xt  supplies  three  basic  classes  that  are  used  as  the  basis  for  custom  widgets,  Core,  Compos 
ite,  and  Constraint.*  Figure  5-1  also  shows  the  relationship  of  these  classes  to  each  other. 
Core  is  the  class  upon  which  all  widgets  are  based.  It  defines  common  characteristics  of  all 
widgets,  such  as  their  methods,  and  basic  resources  such  as  height  and  width.  Even  if  your 
widget  is  unlike  any  existing  widget,  it  will  still  inherit  features  from  the  Core  widget.  The 
class  and  instance  structures  of  a  subclass  of  Composite  such  as  Box  begin  with  the  fields 
from  Core,  continue  with  fields  from  Composite,  and  end  with  the  fields  defined  by  Box. 
Composite  and  Constraint  are  subclasses  of  Core  that  have  additional  methods  that  allow 
them  to  manage  children;  they  are  described  in  Chapter  11,  Geometry  Management.  This 
chapter  concentrates  on  the  features  of  the  Core  widget 

Xt  requires  that  you  implement  each  class's  new  fields  as  a  separate  structure  called  a  Part, 
and  then  combine  this  Part  structure  with  each  superclass's  Part  structure  in  the  complete 
structure  called  a  Rec,  or  record.  In  real  code,  these  structures  are  called 
widgetnameClassPart  and  widgetnameClassRec  for  the  class  structure,  and  simply 
widgetnamePazt  and  widgetnameRec  for  the  instance  structure. 


*Shell,  the  fourth  Litrinsics-supplied  widget  class,  is  not  usually  subclassed  by  application  or  widget  programmers. 
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The  reason  for  this  "structure  within  a  structure"  design  is  primarily  to  reduce  the  changes  in 
the  code  of  subclasses  that  would  be  required  if  changes  were  made  to  the  superclass's  struc 
tures.  As  we  will  see  later,  only  the  portion  of  the  .c  file  that  initializes  the  class  structure 
will  need  changing  if  a  superclass  class  structure  is  changed.  A  second  benefit  of  this  design 
is  that  it  reduces  the  amount  of  typing  required  to  implement  a  new  class. 


5.2.2   Class  Part  and  Class  Record 

Let's  make  these  ideas  concrete  by  showing  the  class  structure  for  BitmapEdit.  The  complete 
class  structure  is  called  BitmapEdit ClassRec,  and  the  partial  structure  is  called 
BitmapEditClassPart.  Their  definitions  from  BitmapEditP .h  are  shown  in  Example 
5-1. 

Example  5-1.  BitmapEditP. h:  the  class  part  and  class  record 

/* 

*  BitmapEditP. h  -  Private  definitions  for  BitmapEdit  widget 
*/ 

/*  protect  against  multiple  including  of  this  file  */ 
#ifndef  _ORABitmapEditP_h 
fdefine  _ORABitmapEditP_h 

ill  /* 

*  This  include  not  needed  unless  the  .c  file  includes 

*  IntrinsicP.h  after  this  file.    Anyway,  it  doesn't  hurt. 
*/ 

tinclude  <Xll/CoreP .h> 

/* 

*  This  one  is  always  needed! 

II    */ 

#include  "BitmapEdit .h" 

/*  New  fields  for  the  BitmapEdit  widget  class  record  */ 

typedef  struct  { 

int  make_compiler_happy;    /*  need  dummy  field  */ 
}  BitmapEditClassPart; 

/*  Full  class  record  declaration  */ 
typedef  struct  _BitmapEditClassRec  { 

CoreClassPart  core_class; 

BitmapEditClassPart     bitmapEdit_class; 
}  BitmapEditClassRec; 

Like  most  widget  classes,  BitmapEdit  provides  no  new  fields  in  the  class  part,  but  it  needs 
one  dummy  member  to  make  the  C  compiler  happy.  Few  classes  define  new  class  part  fields 
because  the  Core  class  already  provides  all  the  class  fields  that  Xt  knows  what  to  do  with.* 


*Nevertheless,  adding  new  fields  does  have  its  uses.  If  you  place  a  new  method  field  here,  subclasses  can  choose  to 
inherit  the  function  or  to  replace  it  However,  the  widget  code  will  have  to  call  the  method  itself  because  Xt  doesn't 
know  when  to.  This  fine  point  is  described  in  Section  1 1 .4.5. 
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The  CorePart  and  CoreClassPart  structures  are  defined  in  Core's  private  header  file 
<XlllCoreP.h>.  In  general,  you  need  to  include  the  private  header  file  of  the  superclass  at 
the  top  of  your  private  header  file.  It  turns  out  that  if  the  header  files  at  the  top  of  the  .c  file 
are  in  the  right  order,  and  the  superclass  of  your  class  is  Core,  Composite,  or  Constraint  (a 
class  defined  by  Xt),  then  this  header  file  doesn't  need  to  be  included.  But  it  doesn't  hurt  to 
do  so,  because  the  header  files  begin  with  an  if  ndef  statement  that  allows  the  preprocessor 
to  make  sure  that  no  header  file  is  included  twice. 


5.2.3   Instance  Part  and  Instance  Record 

The  instance  record  is  built  exactly  like  the  class  structure,  by  defining  new  fields  in  a  part 
structure,  and  then  combining  the  instance  parts  of  all  superclasses  in  the  instance  record. 
BitmapEditPart  defines  BitmapEdit's  new  widget  instance  fields,  and  the  entire  widget 
instance  record  is  BitmapEditRec.  These  structures  are  defined  in  BitmapEditP .h  (along 
with  the  class  structures  just  shown)  and  are  shown  in  Example  5-2.  We've  included  several 
likely  instance  variables,  but  none  of  those  shown  is  an  essential  part  of  the  widget  structure. 

Example  5-2.  BitmapEditP.h:  the  instance  part  and  instance  record 

/*  New  fields  for  the  BitmapEdit  widget  record  */ 
typedef  struct  { 

/*  resources  */ 

Pixel   foreground; 

XtCallbackList   callback;/*  application  installed  callback  fns  */ 

Dimension   pixmap_width_in_cells; 

Dimension   pixmap_height_in_cells; 

int   cell_size; 

int   cur  x,  cur_y;  /*  pstn  of  visible  corner  in  big  pixmap  */ 

char   *ce~ll;        /*  for  keeping  track  of  array  of  bits  */ 

/*  private  state  */ 
Dimension   pixmap_width_in_pixels; 
Dimension   pixmap_height_in_pixels; 
Pixmap   big_picture; 

GC   draw  gc;        /*  for  drawing  into  pixmap  */ 
GC   undraw_gc;     /*  for  undrawing  into  pixmap  */ 
GC   copy_gc:;        /*  for  copying  pixmap  into  window  */ 
}  BitmapEditPart; 

/* 
*  Full  instance  record  declaration 

*/ 

typedef  struct  _BitmapEditRec  { 

CorePart       core; 

BitmapEditPart  bitmapEdit ; 
}  BitmapEditRec; 

tendif  /*  _ORABitmapEditP_h  */ 

Unlike  the  class  part,  which  generally  defines  no  new  fields,  the  instance  part  of  most  widgets 
does  define  new  instance  variables.  These  variables  control  all  the  configurable  elements  of 
the  widget,  and  they  hold  the  widget's  state. 
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Some  of  these  instance  variables  are  resources  because  they  are  listed  in  the  resource  list  in 
the  BitmapEdit.c  file.  (This  resource  list  has  exactly  the  same  format  as  the  resource  list  you 
saw  in  the  application  code  in  Section  3.5.2).  These  variables  are  known  as  public  instance 
variables  (because  they  are  readable  and  writable  from  the  application).  By  convention,  the 
public  instance  variables  are  placed  first  in  the  instance  part  structure,  and  comments  indicate 
which  fields  are  public.  When  the  application  instantiates  the  widget,  Xt  sets  the  public  fields 
based  on  the  resource  databases,  the  command  line  (the  -xrm  form),  and  the  argument  list 
passed  to  xtCreateWidget.  Later  on,  the  application  may  change  these  fields  using  xt- 
SetValues. 

The  private  instance  structure  fields  (not  listed  in  the  widget's  resource  list)  are  either 
derived  from  resource  values  or  they  hold  some  aspect  of  the  widget's  state  (such  as  whether 
it  is  highlighted).  As  in  Example  5-2,  graphics  contexts  (GCs)  are  always  fojund  here  as  pri 
vate  fields  if  the  widget  draws  any  graphics.  Graphics  contexts  are  needed  for  doing  draw 
ing,  and  are  derived  from  public  instance  structure  fields  such  as  colors  and  fonts,  because  it 
is  the  GC  that  actually  carries  color  and  font  information  to  the  X  server.  GCs  were  intro 
duced  in  Section  4.3.1. 

You  may  notice  that  the  Part  structures  of  the  superclasses  are  referenced  in  the  Bitmap- 
EditRec  structure.  As  mentioned  earlier,  you  get  these  by  including  the  private  include  file 
of  the  immediate  superclass,  which  in  turn  includes  the  private  include  file  of  its  own  super 
class,  and  so  on. 

Note  that  both  the  class  and  instance  structures  defined  in  BitmapEditP .h  are  typedef  tem 
plates;  they  do  not  allocate  storage.  Xt  allocates  storage  for  the  instance  record  when  the 
application  calls  XtCreateWidget  or  XtCreateManagedWidget  to  create  the 
widget  The  class  record,  on  the  other  hand,  is  initialized  statically  (at  compile  time)  in  the  .c 
file.  To  make  sure  that  the  definition  of  the  class  record  (in  BitmapEditP  .K)  and  the  initializa 
tion  of  the  class  record  (in  BitmapEdit.c)  use  identical  structures,  BitmapEditP  .h  contains  an 
extern  reference  to  the  class  structure  initialized  in  BitmapEdit.c.  This  reference  is  shown 
in  Example  5-3.  If  a  field  is  accidentally  left  out  of  the  class  structure  in  either  file,  the  com 
piler  will  catch  the  problem  (but  if  the  same  member  is  left  out  of  both  files,  the  problem 
won't  be  caught  and  Xt  will  likely  dump  core). 

Example  5-3.  BitmapEditP.h:  declaring  the  external  class  record 
extern   BitmapEditClassRec   bitmapEditClassRec; 

The  naming  conventions  for  the  various  structure  declarations  in  the  private  header  file  are 
important,  and  can  be  confusing.  A  table  summarizing  the  conventions  for  types  and  vari 
ables  in  the  widget  implementation  files  is  shown  in  Section  5.6  (after  the  contents  of  the  .c 
and  .h  files  are  shown). 

That's  all  there  is  in  the  private  header  file!  If  you  should  need  to  refer  back  to  the  private 
header  file  for  BitmapEdit,  it  is  listed  with  the  rest  of  the  source  for  the  widget  in  Appendix 
B,  The  xbitmap  Application. 
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5.3  The  Widget  Source  File— BitmapEdit.c 


The  central  element  of  the  .c  file  is  the  initialization  of  the  class  record.  Remember  that  the 
typedef  of  the  class  record  was  declared  in  BitmapEditP  .h,  but  the  record  is  allocated  and 
the  actual  values  in  each  field  are  set  in  BitmapEdit.c.  When  Xt  takes  over  control  of  the 
widgets  after  the  application  calls  xtMainLoop,  it  is  the  values  in  this  class  record  that 
supply  Xt  with  all  the  information  it  uses  to  manage  widget  instances. 

The  organization  of  the  .c  file  is  quite  simple.  First,  it  defines  everything  that  will  be  placed 
into  the  class  record,  and  then  initializes  the  class  record,  setting  fields  using  these  defini 
tions.  The  major  things  that  need  defining  are  the  functions  that  implement  each  method,  the 
resource  list,  the  translation  table,  and  the  actions  table.  It  would  be  logical  to  define  these 
four  things  at  the  beginning  of  the  source  file,  and  then  put  the  class  record  last.  This  is 
almost  the  case,  except  that  by  convention  the  methods  and  actions  are  declared  at  the  top  of 
the  source  file  and  then  defined  at  the  end  after  the  class  record  initialization.  This  actually 
makes  the  widget  code  clearer  because  the  method  declarations  provide  a  complete  list  of  the 
methods  that  will  be  defined  later  in  the  file,  and  the  class  record  remains  near  the  top  of  the 
file  where  it's  easier  to  find.  (Not  all  the  methods  have  to  be  defined  by  a  class,  because  some 
methods  can  be  inherited  or  not  used,  as  we  will  discuss  in  Section  5.3.6.)  Figure  5-2  sum 
marizes  the  conventional  order  of  code  in  the  .c  file.* 


5.3.1    Obligatory  Include  Files 

The  .c  file  begins  with  the  standard  includes: 

•  <stdio.h>,  since  print f  always  comes  in  handy  for  debugging  purposes. 

•  <X1  II Intrinsic?. h>   (which  includes   <XlllIntrinsic.h>)  for  the  Xt  supplied  widget 
classes  Core,  Composite,  and  Constraint,  declarations  of  Intrinsics  functions,  and  several 
useful  macros. 

•  <XlllStringDefs.h>  for  the  standard  resource  names  used  in  defining  the  resource  list. 

Example  5-4.  BitmapEdit.c:  include  files 
tinclude    <stdio.h> 

tinclude  <Xll/StringDef s .h> 
tinclude  <Xll/IntrinsicP .h> 

#include  "BitmapEditP .h" 

Remember  that  BitmapEditP. h  includes  the  private  header  file  of  the  immediate  superclass 
(which  includes  the  private  header  file  of  its  own  superclass,  and  so  on),  and  each  private 


"Here  we  use  the  terminology  defined  in  Kemighan  and  Ritchie's  The  C  Programming  Language  (Prentice-Hall 
1978).  A  declaration  announces  the  properties  of  a  variable  (its  type,  size,  etc.),  while  a  definition  causes  storage  to 
be  allocated.  This  distinction  is  important  in  the  Toolkit  because  many  things  are  declared  and  defined  in  separate 
steps. 
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header  file  includes  the  public  header  file  for  its  class,  so  that  all  the  information  in  all  the 
public  and  private  header  files  for  all  superclasses  is  available  to  this  .c  file  as  a  result  of  this 
one  include  statement. 


Structure  of  widget  .c  File 


Header  Files 


Resource  List 


Action  Function  Declarations 


Actions  Table 


Default  Translation  Table 


Method  Function  Declarations 


Class  Record  Initialization 


Method  Function  Definitions 


Action  Function  Definitions 


#include 


~~L   static  XtResource  resources  =  {  }; 
p   static  void  Action  (); 


static  XtActionsRec  actions  []={}; 
static  char  def aultTranslations []=""; 
static  void  Initialize (),  Redisplay (); 

NewWidgetClassRec  newWidgetClassRec={ } 
{ 

/*CoreClassPart,etc. */ 
} 

static  void  Initialize () 


static  void  Action () 


Figure  5-2.  Order  of  code  in  widget  .c  file 

We'll  look  at  BitmapEdit.c  in  seven  parts,  in  an  order  corresponding  to  Figure  5-2. 
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5.3.2   Defining  the  Resource  List 

A  widget  inherits  the  resources  defined  by  its  superclasses,  and  it  can  also  add  its  own 
resources  by  defining  a  resource  list  and  setting  it  into  the  class  structure.  This  section 
reviews  the  basic  techniques  for  creating  a  resource  list,  since  this  technique  was  shown  in 
Chapter  4  when  we  added  application  resources  to  xbitmap. 

In  creating  an  application  resource  list,  we  created  a  structure  called  app_data  whose 
fields  were  to  be  set  through  resources.  In  widget  code,  the  instance  part  structure  is  used  just 
like  app_data,  except  that  the  private  instance  structure  fields  will  not  appear  in  the 
resource  list.  Each  member  of  the  instance  structure  that  is  to  be  a  resource  must  have  an 
entry  in  the  resource  list. 

Example  5-5  shows  a  resource  list  for  the  public  instance  variables  defined  in  Example  5-2 
above. 

Example  5-5.  BitmapEdit's  resource  list 

static  XtResource  resources!]  =  { 

{ 

XtNforeground, 
XtCForeground, 
XtRPixel, 
sizeof (Pixel)  , 

offset (bitmapEdit . foreground)  , 
XtRString, 
XtDefaultForeground 

}, 

{ 

XtNcallback, 
XtCCallback, 
XtRCallback, 
sizeof (caddr_t) , 
offset (bitmapEdit . callback)  , 
XtRCallback, 
NULL 

}, 

{ 

XtNcellSizelnPixels, 
XtCCellSizelnPixels, 
XtRInt,  sizeof (int), 

offset (bitmapEdit .cell_size_in_pixels) , 
XtRImmediate, 
(caddr_t) DEFAULT_CELL_SIZE 

}, 

{ 

XtNpixmapWidthlnCells, 
XtCPixmapWidthlnCells, 
XtRDimension, 
sizeof (Dimension)  , 

offset (bitmapEdit .pixmap_width_in_cells)  , 
XtRImmediate, 
(caddr_t) DEFAULT_PIXMAP_WIDTH 
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Example  5-5.  BitmapEdit's  resource  list  (continued) 

XtNpixmapHeightlnCells, 

XtCPixmapHeightlnCells, 

XtRDimension, 

sizeof  (Dimension)  , 

offset  (bitmapEdit  .pixmap_height_in_cells)  , 

XtRImmediate, 

(caddrt)  DEFAULT_PIXMAP_HEIGHT 


XtNcurX, 
XtCCurX, 
XtRInt, 
sizeof  (int  )  , 

offset  (bitmapEdit  .  cur_x) 
XtRImmediate, 
(caddr_t)  0 


XtNcurY, 
XtCCurY, 
XtRInt, 
sizeof  (int)  , 

offset  (bitmapEdit  .  cur_y  )  , 
XtRString, 
(caddr_t)  NULL 


XtNcellArray, 

XtCCellArray, 

XtRString, 

sizeof  (String)  , 

offset  (bitmapEdit  .cell)  , 

XtRImmediate, 

(caddr_t)  0 


As  mentioned  earlier,  a  widget  class  inherits  all  the  resources  defined  in  the  resource  lists  of 
its  superclasses.  If  a  resource  is  given  the  same  name  as  a  superclass  resource,  it  overrides 
the  superclass  resource.  The  only  reason  to  create  a  new  resource  with  the  same  name  as  a 
superclass  resource  is  to  give  it  a  new,  subclass-specific  default  value.  The  type  and  offset 
should  remain  the  same. 

When  defining  a  resource  list,  use  as  many  as  possible  of  the  constants  defined  in 
<XlllStringDefs.h>.  However,  any  constant  unique  to  this  widget  class  can  be  defined  in  the 
public  include  file,  as  will  be  described  in  the  next  section. 

Table  5-1  summarizes  the  conventions  for  the  constants  used  in  the  resource  list. 
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Table  5- 1.  Resource  list  constant  conventions 


Prefix 

First  word  capitalization 

Description 

XtN 

xtc 

XtR 

Lower 
Upper 
Upper 

Resource  name 
Resource  class 
Representation  type 

Xt  constants  and  functions  of  all  types  use  upper  case  letters  whenever  a  word  break  might 
otherwise  be  called  for.  Two  examples  of  resource  names  following  this  convention  are  xt- 
NborderColor  and  XtNmappedWhenManaged. 

Example  5-6  shows  how  the  resource  list  is  entered  into  the  class  structure.  You'll  see  this 
again  in  Section  5.3.5  where  we  show  the  entire  class  record  and  describe  how  to  initialize  it. 
The  names  of  the  fields  in  the  class  structure  are  shown  in  the  comments  at  right. 

Example  5-6.  Setting  the  resource  list  into  the  class  structure 

BitmapEditClassRec  bitmapEditClassRec  =  { 
{   /*  Core  class  part  */ 


resources, 

XtNumber (resources)  , 


/*  resources  */ 

/*  resource  count      */ 


/*  BitmapEdit  class  part  */ 


0, 


/*  dummy  field  */ 


Note  that  a  widget  or  an  application  can  get  the  resource  list  for  a  class  using  xtGet- 
ResourceList,  which  returns  a  pointer  to  a  resource  list  of  the  same  form  as  shown 
above.  This  function  isn't  needed  in  most  applications  or  widgets. 


>.3.3  The  Translation  Table  and  Actions  Table 

You  may  recall  that  the  translation  table  maps  event  sequences  into  string  action  names,  and 
the  action  table  then  maps  string  action  names  into  actual  action  functions.  This  is  done  in 
two  steps  so  that  the  translation  table  is  a  single  string  that  can  be  specified  in  the  resource 
databases  (since  resource  databases  are  always  composed  entirely  of  strings).  The  action 
table  is  not  configurable  through  the  resource  database,  but  it  can  be  modified  from  the  appli 
cation  or  from  the  widget  code  with  xtAddAction  (s) ,  xtRemoveAction  (s) ,  or 
XtRemoveAllActions. 

Like  the  resource  list,  the  default  translation  table  and  the  actions  table  have  to  be  defined 
before  the  class  record  can  be  initialized.  They  determine  which  events  this  widget  will 
respond  to,  and  which  functions  defined  in  this  source  file  will  be  triggered  by  those  events. 
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The  translation  table  is  a  resource  defined  by  the  Core  class.  It  is  a  strange  resource  in  sev 
eral  ways.  It  has  no  default  value  in  the  resource  list.  Instead,  the  default  translation  table  is 
initialized  into  the  class  structure.  Translations  are  not  inherited  like  other  resources — you 
do  not  get  the  sum  of  all  the  translation  tables  registered  by  the  superclasses.  Rather,  the 
translation  table  you  specify  in  the  class  structure  is  the  only  one  (in  the  code)  that  matters. 
However,  you  can  choose  to  use  the  immediate  superclass's  translation  table,  in  which  case 
you  initialize  the  translation  table  field  in  the  class  structure  to  be  xt  inherit - 
Translations. 

Each  widget  has  its  own  action  list,  and  if  the  application  registers  an  action  list,  it  is  kept  as 
a  separate  list.  When  an  event  combination  occurs  in  a  widget,  Xt  translates  the  event  combi 
nation  into  an  action  string  and  searches  that  widget's  action  list.  If  the  action  string  is  found 
in  the  widget's  action  list,  the  search  stops  and  that  action  function  is  called.  If  the  action 
string  is  not  found  in  the  widget's  action  list,  then  the  application's  action  list  is  searched.  If 
neither  list  contains  the  appropriate  action  string,  Xt  prints  a  diagnostic  warning.  If  the  appli 
cation  and  the  widget  both  define  the  same  action  string  in  the  actions  table,  the  application's 
function  mapped  to  that  string  will  never  be  called.  Two  widget  classes,  however,  may  have 
the  same  action  function  name,  and  they  will  not  conflict. 

Example  5-7  shows  a  default  translation  table  and  an  action  table.  Note  that,  like  methods, 
the  action  functions  are  declared  before  being  used  in  the  actions  table,  but  they  will  actually 
be  defined  later  in  the  source  file. 

Example  5-7.  The  default  translation  table  and  the  actions  table 
static   void  DrawCellO,    UndrawCell ( ) ,    ToggleCell  O; 

static  char  defaultTranslations []  = 

"<BtnlDown>:     DrawCellO  \n\ 

<Btn2Down>:     UndrawCell ()  \n\ 

<Btn3Down>:     ToggleCell {)  \n\ 

<BtnlMotion>:   DrawCellO  \n\ 

<Btn2Motion>:   UndrawCell ()  \n\ 

<Btn3Motion>:   ToggleCell O "; 
static  XtActionsRec  actions!]  =  { 
{"DrawCell",  DrawCell}, 
{"UndrawCell",  UndrawCell}, 
{"ToggleCell",  ToggleCell}, 
}; 

The  pointers  to  the  actions  table  and  translation  table  are  placed  into  the  class  structure  just 
like  the  resource  list  (but  of  course  into  different  fields),  as  shown  in  Example  5-8.  The 
names  of  the  fields  in  the  class  structure  are  shown  in  the  comments  at  right.  (You'll  see  this 
again  shortly  in  the  section  on  class  structure  initialization.) 

Example  5-8.  Translations  in  the  Core  Class  Record 

BitmapEditClassRec  bitmapEditClassRec  =  { 
{   /*  core  class  part  */ 

actions,  /*  actions  */ 

XtNumber (actions) ,  /*  num  actions  */ 
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Example  5-8.  Translations  in  the  Core  Class  Record  (continued) 


default  Translations, 


0, 


/*  tm  table 


*/ 


/*  BitmapEdit  class  part  */ 
/*  dummy  field  */ 


Note  that  the  default  translation  table  cannot  be  compiled  with  xtParseTranslation- 
Table  before  being  placed  in  the  class  structure,  since  the  class  structure  initialization 
occurs  at  compile  time.  Xt  compiles  the  default  translations  when  the  class  is  initialized. 

The  translation  table  and  actions  table  are  discussed  more  fully  in  Chapter  7,  Events,  Transla 
tions,  and  Accelerators. 


5.3.4    Declaring  Methods 

The  widget's  methods  should  be  declared  near  the  top  of  the  .c  file.  This  is  so  that  the  class 
structure  initialization  can  appear  before  the  method  definitions.  IntrinsicP.h  declares 
typedefs  for  each  type  of  function  that  will  be  a  widget  method.  For  example,  the 
expose  method  (to  be  described  later  in  this  chapter)  is  a  function  of  type  XtExpose 
Proc.  XtExposeProc  is  actually  defined  to  be  void. 

However,  these  typedefs  do  not  seem  to  work  on  all  compilers.  The  Athena  widgets  don't 
use  them  to  declare  their  methods.  Instead,  they  use  the  actual  type  returned,  such  as  void 
or  Bool.  You  should  probably  do  this  too.  Example  5-9  shows  the  method  declarations 
from  BitmapEdit  done  both  ways,  with  the  typedef  approach  commented  out 

Example  5-9.  BitmapEdit.c:  function  type  declarations 

/*  Declaration  of  methods  */ 

These  function  prototype  declarations  don't  work  under 
SunOs  4.0.1  and  perhaps  others  so  we'll  instead  declare 
the  actual  return  type 

static  XtlnitProc  Initialize O ; 
static  XtExposeProc  Redisplay O; 

*  static  XtWidgetProc  Destroy O  ; 

*  static  XtWidgetProc  Resize O ; 

*  static  XtSetValuesFunc  SetValuesO; 
*/ 

static  void  Initialize  O; 

static  void  Redisplay O; 

static  void  Destroy  O; 

static  void  Resize O ; 

static  Boolean  SetValuesO; 

static  XtGeometryResult  QueryGeometry () ; 

/*  these  Core  methods  not  needed  by  BitmapEdit: 

* 
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Example  5-9.  BitmapEdit.c:  function  type  declarations  (continued) 

static  XtProc  Classlnitialize  (); 
static  XtRealizeProc  Realize (); 
static  void  Classlnitialize (); 
static  void  Realize (); 

/*  the  following  are  functions  private  to  BitmapEdit  */ 
static  void  DrawPixmaps { ) ,  DoCelK),  ChangeCellSize ( ) ; 

/*  the  following  are  actions  of  BitmapEdit  */ 
static  void  DrawCellO,  UndrawCell ( ) ,  ToggleCell ( ) ; 

By  convention,  the  names  of  function  typedefs  in  Xt  end  in  Proc  or  Func.  Also  by  conven 
tion,  function  typedefs  ending  in  Func  return  a  meaningful  value,  while  those  ending  in 
Proc  return  void.  A  basic  description  of  all  the  methods  is  given  in  Section  5.3.6. 

Notice  that  several  methods  use  the  same  typedefs.  For  example,  xtwidgetProc  is  the 
type  of  several  methods  (destroy,  resize,  and  others).  Volume  Five,  X  Toolkit  Intrin- 
sics  Reference  Manual,  summarizes  the  calling  sequence  for  each  typedef,  and  its  multiple 
uses  when  appropriate. 

The  methods  are  declared  static  to  prevent  access  to  the  functions  from  outside  this 
source  file,  and  to  prevent  collisions  with  other  functions  of  the  same  name  in  other  source 
files. 


5.3.5   Initializing  the  Class  Record 

We've  already  shown  you  how  to  create  the  resource  list,  the  translation  table,  and  the 
actions  table,  and  set  into  the  class  structure.  A  major  part  of  the  work  is  done.  Now  we  just 
need  to  insert  the  method  function  names  we  declared  earlier  into  the  class  record,  and  set  a 
few  of  the  miscellaneous  data  fields. 

As  we  saw  in  the  discussion  of  the  private  header  file,  the  BitmapEdit  class  record  includes 
class  parts  for  BitmapEdit  itself  and  for  each  superclass  of  BitmapEdit,  in  this  case  only 
Core.  To  initialize  the  class  record,  each  class  part  has  to  be  initialized  field  by  field.  But  for 
simple  (noncomposite)  widgets  this  job  comes  down  to  initializing  the  Core  class  part, 
because  few  classes  actually  define  new  class  part  fields. 

5.3.5.1    The  Core  Class  Part 

Since  all  widget  classes  are  subclasses  of  Core,  all  need  to  initialize  the  Core  class  part. 
Example  5-10  shows  the  core  part  initialized  as  needed  by  the  BitmapEdit  widget.  The 
actual  name  of  each  field  is  shown  in  the  comment  at  left.  Each  field  will  be  discussed  after 
the  example. 

Example  5-10.  BitmapEdit.c:  initialization  of  Core  class  record 

BitmapEditClassRec  bitmapEditClassRec  =  { 
{ 
/*  core  class  fields  */ 
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Example  5-10.  BitmapEdit.c:  initialization  ol  Core  class  record  (continued) 


/*  superclass 

/*  class_name 

/*  widget_size 

/*  class_initialize 

/*  class_part_initialize 

/*  class_inited 

/*  initialize 

/*  initialize_hook 

/*  realize 

/*  actions 

/*  num_actions 

/*  resources 

/*  num_resources 

/*  xrm_class 

/*  compress_motion 

/*  compress_exposure 

/*  compress_enterleave 

/*  visible_interest 

/*  destroy 

/*  resize 

/*  expose 

/*  set_values 

/*  set_values_hook 

/*  set_values_almost 

/*  get_values_hook 

/*  accept_focus 

/*  version 

/*  callback_private 

/*  tm_table 

/*  query_geometry 

/*  display_accelerator 

/*  extension 


*/  (WidgetClass)  SwidgetClassRec, 

*/  "BitmapEdit", 

*/  sizeof (BitmapEditRec) , 

*/  NULL, 

*/  NULL, 

*/  FALSE, 

*/  Initialize, 

*/  NULL, 

*/  XtlnheritRealize, 

*/  actions, 

*/  XtNumber (actions) , 

*/  resources, 

*/  XtNumber (resources) , 

*/  NULLQUARK, 

*/  TRUE, 

*/  TRUE, 

*/.  TRUE, 

*/  FALSE, 

*/  Destroy, 

*/  Resize, 

*/  Redisplay, 

*/  SetValues, 

*/  NULL, 

*/  XtlnheritSetValuesAlmost, 

*/  NULL, 

*/  NULL, 

*/  XtVersion, 

*/  NULL, 

*/  defaultTranslations, 

*/  QueryGeometry, 

*/  XtlnheritDisplayAccelerator, 

*/  NULL 


{  /*  BitmapEdit  class  part*/ 
/*  dummy_field  */ 


If  you  are  like  most  programmers,  the  core  class  structure  is  the  biggest  structure  you  have 
ever  seen!  Don't  worry,  because  many  of  the  fields  you  will  never  have  to  worry  about,  and 
the  rest  you  will  gradually  come  to  know  as  you  need  them.  We  will  introduce  all  the  fields 
here,  but  you  are  not  expected  to  absorb  all  the  details  in  a  single  sitting.  Treat  this  section 
both  as  an  introduction  and  as  a  summary  to  which  you  can  turn  back  when  you  encounter  a 
field  you  don't  understand.  Also,  all  of  the  methods  and  some  of  the  data  fields  will  be 
described  in  more  detail  later  in  the  book.  These  field  descriptions  reference  the  section  in 
this  book  where  you  will  find  additional  information  about  the  field. 

•  The  superclass  defines  a  pointer  to  the  superclass's  class  structure.  This  defines 
which  widgets  this  class  can  inherit  from.  For  a  subclass  of  Core  this  would  be 
SwidgetClassRec;  for  a  subclass  of  Composite,  ScompositeClassRec;  for  a 
subclass  of  Constraint,  &constraintClassRec,andsoon. 
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The  next  field,  class_name,  contains  the  name  that  will  be  used  to  set  resources  by 
class.  In  other  words,  this  is  the  string  that  you  want  to  appear  in  the  resource  database 
when  setting  resources  for  all  instances  of  this  class. 

The  widget_size  field  is  the  size  of  the  instance  record.  This  should  always  be  speci 
fied  using  sizeof  with  the  complete  instance  record  declaration  for  this  class,  defined 
in  BitmapEditP.h,  as  an  argument  In  this  case  the  field  is  initialized  to 
sizeof  (BitmapEditRec) .  Xt  uses  this  field  to  allocate  memory  for  instance 
records  at  run-time. 

The  next  field,  class_initialize,  is  the  first  of  many  pointers  to  widget  methods. 
There  are  several  issues  regarding  methods  that  require  separate  treatment,  so  we'll 
describe  these  in  the  next  section.  The  complete  list  of  methods  in  the  Core  part  structure 
is  as  follows:  class_initialize,  class_part_init,  initialize,  real 
ize,  destroy,  resize,  expose,  set_values,  set_values_almost, 
query_geometry,  and  accept_f  ocus. 

The  display_accelerator  field  is  used  in  conjunction  with  accelerators,  which 
are  a  way  of  redirecting  events  to  actions  in  different  widgets,  and  will  be  discussed  in 
more  detail  in  Chapter  9,  Resource  Management  and  Type  Conversion. 

The  class_inited  field  is  used  internally  by  Xt  to  indicate  whether  this  class  has 
been  initialized  before.  Always  initialize  it  to  FALSE. 

The  initialize_hook,  set_values_hook,  and  get_values_hook  fields 
are  for  use  in  widgets  that  have  subparts  that  are  not  widgets.  Subparts  can  have  their 
own  resources,  and  can  load  them  from  the  resource  databases  like  a  widget  can.  These 
methods  are  called  immediately  after  the  method  of  the  same  name  without  _hook,  and 
are  for  performing  the  same  operations  except  on  subparts.  (The  Text  widget  is  the  only 
Athena  widget  that  has  subparts.)  These  fields  are  described  in  Chapter  9,  Resource  Man 
agement  and  Type  Conversion. 

The  fields  relating  to  resources,  the  default  translation  table,  and  the  actions  table  have 
already  been  described.  The  only  one  of  these  fields  without  an  obvious  name  is  the 
tm_table  field,  in  which  you  place  the  default  translation  table. 

The  xrm_class  field  is  used  internally  by  Xt,  and  must  always  be  initialized  to 
NULLQUARK.  This  is  a  fixed  initialization  value. 

The  compress_motion,  compress_exposure,  and  compress_enterleave 
fields  control  the  Toolkit's  event  filters.  Basically,  these  filters  remove  events  that  some 
widgets  can  do  without,  thus  improving  performance.  Unless  a  widget  performs  compli 
cated  drawing  or  tracks  the  pointer,  these  fields  should  usually  be  TRUE.  These  filters  are 
described  in  Chapter  8,  Other  Input  Sources. 

The  visible_interest  field  can  be  set  to  TRUE  if  your  widget  wishes  to  get 
visibilityNotif y  events,  which  signal  changes  in  the  visibility  of  your  widget 
Normally  this  is  set  to  FALSE,  because  Expose  events  cause  the  widget  to  be  redrawn  at 
the  proper  times.  For  some  widgets,  however,  Expose  events  are  not  enough.  If  your 
widget  draws  continuously,  as  in  a  game,  it  can  stop  computing  output  for  areas  that  are 
no  longer  visible.  There  are  other  cases  where  VisibilityNotif  y  events  are  useful. 
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Xt  uses  the  version  field  to  check  the  compiled  widget  code  against  the  library  the 
widget  is  linked  against.  If  you  specify  the  constant  Xt  Version  and  it  is  different  from 
the  version  used  by  the  libraries,  then  Xt  displays  a  run-time  warning  message.  However, 
if  you  have  intentionally  designed  a  widget  to  run  under  more  than  one  version  of  Xt,  you 
can  specify  the  constant  XtVersionDontCheck. 

The  callback_private  field  is,  as  it  says,  private  to  Xt,  and  you  always  initialize  it 
tO  NULL. 

The  extension  field  is  unused  in  Release  3.  It  is  for  extending  the  Core  widget  in 
later  releases  while  maintaining  binary  compatibility  with  the  current  release. 


5.3.5.2    Initializing  the  Core  Methods 

As  you've  just  seen,  there  are  several  places  for  pointers  to  methods  stored  in  the  Core  class 
structure.  We  will  be  describing  the  purpose  of  each  of  these  methods  in  the  next  section. 
But  first,  a  word  about  how  to  set  the  method  fields. 

Fortunately,  the  Core  class  already  defines  some  of  the  methods,  and  you  can  choose  to 
inherit  them  instead  of  writing  your  own.  In  general,  when  you  set  out  to  write  a  widget,  you 
will  pick  as  your  superclass  the  widget  that  has  the  most  methods  that  you  can  inherit  instead 
of  write  from  scratch. 

Broadly  speaking,  there  are  two  types  of  methods,  self-contained  methods  and  chained  meth 
ods. 

A  self-contained  method  is  one  that  is  called  alone — the  methods  of  the  same  name  in  the 
widget's  superclasses  are  not  called.  For  example,  expose  is  self-contained.  When  you 
write  the  expose  method,  you  are  writing  all  the  drawing  code  for  the  widget.  The 
expose  method  of  the  superclass  will  not  be  called  even  if  it  was  designed  to  do  drawing. 
Therefore,  by  writing  an  expose  method  you  replace  the  expose  method  of  the  super 
class. 

A  chained  method  is  one  that  is  not  called  alone — it  is  called  either  before  or  after  all  the 
methods  of  the  same  name  in  its  superclasses  and  subclasses.  Therefore,  you  can't  replace 
any  of  the  code  in  this  method  in  the  subclasses  or  superclasses,  you  can  only  add  to  it  by 
writing  your  own. 

Inheritance  works  differently  for  each  type  of  method.  For  self-contained  methods,  such  as 
realize  and  expose,  inheritance  works  almost  as  it  does  for  default  translations.  When 
initializing  a  field  in  the  class  record  that  represents  a  self-contained  method,  you  have  three 
choices: 

•  You  can  define  these  methods  in  your  widget  code  by  placing  the  name  of  the  function  in 
the  class  record  and  defining  that  function  somewhere  in  the  source  file. 

•  You  can  inherit  that  method  from  the  immediate  superclass  by  placing  a  special  symbol 
beginning  with  Xt  Inherit  in  that  field  in  the  class  record. 
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•  You  can  use  the  first  technique,  but  reference  the  superclass's  method  in  your  method. 
This  allows  you  to  add  features  to  the  superclass's  method  without  having  to  completely 
copy  it  and  modify  it 

Several  other  methods  such  as  initialize  use  the  other  flavor  of  inheritance  called 
chaining.  These  methods  do  not  supercede  the  methods  of  their  superclasses.  Instead,  the 
methods  in  each  superclass  are  called  in  order.  Some  methods  are  downward  chained,  which 
means  that  the  Core  method  is  called  first,  followed  by  the  same  method  in  each  subclass. 
Other  methods  are  upward  chained,  which  means  that  the  Core  class  method  is  called  last. 
For  both  upward  and  downward  chained  methods,  your  choice  is  whether  to  specify  addi 
tional  code  by  defining  your  own  method,  or  to  go  with  what  the  other  classes  have  already 
defined.  You  cannot  prevent  the  code  from  the  other  classes  from  being  executed. 

Here  is  how  chaining  works  for  the  initialize  method  in  BitmapEdit.  Remember  that 
BitmapEdit  is  a  subclass  of  Core.  The  Core  widget's  class  record  contains  only  the  Core  part 
structure.  The  BitmapEdit  widget's  class  record  contains  the  Core  and  BitmapEdit  part  struc 
tures.  The  initialize  method  is  present  in  the  Core  part  structure  of  both  classes.  When 
an  application  creates  an  instance  of  the  BitmapEdit  widget,  Xt  calls  the  function  specified  in 
the  initialize  field  in  the  Core  class  record  first,  followed  by  the  one  in  the  BitmapEdit 
class  record.  This  is  an  example  of  downward  chaining. 

The  destroy  method,  on  the  other  hand,  is  upward  chained.  That  is,  the  destroy  method 
in  BitmapEdit  would  be  called  first,  followed  by  the  destroy  method  for  Core. 

If  you  specify  NULL  in  your  class  structure  for  a  method  that  chains  upward  or  downward,  it 
is  equivalent  to  specifying  a  function  that  does  nothing.  The  function  for  that  method  of  the 
superclasses  and  subclasses  will  still  be  called  normally. 

Table  5-2  lists  which  methods  fall  into  each  type  of  inheritance.  It  also  shows  how  transla 
tions,  actions,  and  resources  are  chained. 

Table  5-2.  Inheritance  style  of  various  methods 


Self-contained 

Upward  chained 

Downward  chained 

class   initialize 
realize 

destroy 

class   part   init 
initialize 

resize 

set   values 

expose 
accept    focus 
set   values   almost 

get   values   hook 
set   values   hook 
initialize   hook 

query   geometry 
translations 

actions 

resources 
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5.3.6   Description  of  Core  Methods 

Here  is  a  brief  description  of  the  purpose  of  each  Core  method,  and  where  in  this  book  the 
method  will  be  described  in  detail.  All  these  methods,  except  realize,  can  be  set  to  NULL 
in  the  class  record  and  the  widget  will  still  function.  However,  all  widgets  that  draw  into 
their  window  will  also  require  the  expose  method,  the  initialize  method,  and  usually 
the  resize  method.  And  to  be  good  children,  widgets  should  define  a  query_geome- 
try  method.  The  realize  method  is  shown  in  Section  5.3.8,  and  the  rest  of  the  com 
monly-used  methods  immediately  after  that  in  Chapter  6,  Basic  Widget  Methods. 

This  list  describes  all  the  methods,  even  those  that  are  rarely  used.  There  is  a  lot  of  detail 
here  that  you  should  not  expect  to  absorb  in  a  first  reading.  Like  the  list  of  Core  class  struc 
ture  fields,  treat  this  as  an  introduction  and  come  back  to  it  later  for  reference  when  you  come 
across  a  method  you  don't  know  how  to  use,  or  if  you  have  something  you  want  to  do  and 
you  don't  remember  in  which  method  to  do  it 

•  initialize  sets  initial  values  for  all  the  fields  in  the  instance  part  structure.   This 
method  is  responsible  for  checking  that  all  public  fields  have  been  set  to  reasonable  val 
ues.  This  method  is  downward  chained,  so  each  class's  initialize  method  sets  the 
initial  values  for  its  own  instance  part  structure.  This  method  is  described  in  Chapter  6, 
Basic  Widget  Methods. 

•  initialize_hook  is  called  immediately  after  the  initialize  method  of  the  same  class. 
It  allows  the  widget  to  initialize  subparts,  and  is  used  only  in  widgets  that  have  subparts, 
like  the  Athena  Text  widget  Subparts  have  their  own  resources  and  are  described  in  Sec 
tion  9.4.    The  initialize_hook  method  is  also  described  there,    initial- 
ize_hook  is  downward  chained. 

•  class_initialize  is  called  once,  the  first  time  an  instance  of  a  class  is  created  by 
the  application.  The  widget  registers  type  converters  here,  if  it  has  defined  any  nonstan- 
dard  ones.    class_initialize  is  self-sufficient,  and  is  described  in  Chapter  9, 
Resource  Management  and  Type  Conversion. 

•  class_part_init  is  called  once  the  first  time  an  instance  of  a  class  is  created  by  the 
application.    It  is  different  from  class_initialize  only  in  that  it  is  downward 
chained.  This  method  resolves  inheritance  of  self-sufficient  methods  from  the  immediate 
superclass.  It  is  needed  only  in  classes  that  define  their  own  methods  in  their  class  part 
(but  is  not  present  in  Core,  Composite,  or  Constraint,  because  Xt  handles  inheritance  in 
these).   This  method  is  described  in  Chapter  13,  Miscellaneous  Toolkit  Programming 
Techniques. 

•  realize  is  called  when  the  application  calls  XtRealizeWidget.  This  method  is 
responsible  for  setting  window  attributes  and  for  creating  the  window  for  the  widget.  It  is 
self-sufficient,  and  is  described  in  Section  5.3.8. 

•  expose  redraws  a  widget  whenever  an  Expose  event  arrives  from  the  server  (but  note 
that  Xt  can  coalesce  consecutive  Expose  events  to  minimize  the  number  of  times  it  is 
called).  This  method  is  responsible  for  making  Xlib  calls  to  draw  in  the  widget's  win 
dow.  The  widget's  instance  variables  are  often  used  in  the  expose  method  to  guide  the 
drawing.  This  method  is  self-sufficient  This  method  is  described  in  Chapter  6,  Basic 
Widget  Methods. 
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•  resize  is  called  when  the  parent  widget  resizes  the  widget  It  recalculates  the  instance 
variables  based  on  the  new  position  and  size  of  its  window,  which  are  passed  into  the 
method.  This  method  is  self-sufficient  and  is  described  in  Chapter  6,  Basic  Widget  Meth 
ods,  and  in  Chapter  11,  Geometry  Management. 

set_values  is  called  whenever  the  application  calls  xtSetValues  to  set  the 
resources  of  the  widget  This  method  recalculates  private  instance  variables  based  on  the 
new  public  instance  variable  values.  It  contains  similar  code  to  the  initialize 
method,  but  is  called  at  different,  and  perhaps  multiple,  times.  The  set_values 
method  is  downward  chained.  This  method  is  described  in  Chapter  6,  Basic  Widget 
Methods. 

set_values_almost  is  used  to  process  application  requests  to  change  this  widget's 
size.  This  field  should  never  be  NULL.  Unless  you've  written  your  own  set_val- 
ues_almost  method,  this  field  should  be  set  to  Xt Inherit SetValuesAlmost. 
Most  classes  inherit  this  procedure  from  their  superclass.  This  method  is  self-contained 
and  is  described  in  Chapter  11,  Geometry  Management. 

set_values_hook  sets  resource  values  in  subparts.  This  method  is  used  only  in 
widgets  that  have  subparts,  as  described  in  Section  9.4.  It  is  downward  chained  and  is 
described  in  Chapter  9,  Re  source  Management  and  Type  Conversion. 

•  accept_f  ocus  is  NULL  for  most  widgets  (or,  at  least,  for  all  the  Athena  widgets). 
When  it  is  present,  this  method  should  set  the  keyboard  focus  to  a  subwidget  of  this 
widget.  This  would  be  used,  for  example,  to  allow  the  application  to  set  the  input  focus 
to  the  Text  widget  within  a  Dialog  widget.  This  method  is  invoked  when  the  application 
calls  xtCallAcceptFocus.  This  method  is  self-contained  and  is  described  in  Chap 
ter  13 ,  Miscellaneous  Toolkit  Programming  Techniques. 

•  get_values_hook  is  called  just  after  get_values  and  is  used  to  return  the 
resources  of  subparts.  This  method  is  downward  chained  and  is  described  in  Chapter  9, 
Resource  Management  and  Type  Conversion. 

•  destroy  deallocates  local  and  server  memory  allocated  by  this  widget.  This  is  called 
when  an  application  destroys  a  widget  but  remains  running.  This  method  is  described  in 
Chapter  6,  Basic  Widget  Methods. 

•  query_geometry  may  be  called  when  the  parent  widget  is  about  to  resize  the  widget. 
The  method  is  passed  the  proposed  new  size,  and  is  allowed  to  suggest  a  compromise 
size,  or  to  agree  to  the  change  as  specified.  This  method  it  self-contained.  It  is  described 
in  Chapter  6,  Basic  Widget  Methods. 

Initialization  of  the  Composite  and  Constraint  class  parts,  including  the  methods  in  those 
structures,  is  described  in  Chapter  11,  Geometry  Management,  since  this  is  necessary  only  in 
widgets  that  manage  children. 
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5.3.7  Packaging  the  Class  Record  for  Application  Use 

The  final  requirement  of  the  .c  file  is  a  pointer  to  the  class  record,  called  bitmapEdit- 
WidgetClass,  that  applications  use  as  an  argument  to  xtCreateManagedWidget  to 
create  instances  of  this  widget  class.  This  is  shown  in  Example  5-11. 

Example  5-11.  BitmapEdit.c:  declaring  the  class  record  pointer 

WidgetClass  bitmapEditWidgetClass  =  (WidgetClass)  sbitmapEditClassRec; 

bitmapEditWidgetClass  is  set  to  be  a  pointer  to  the  bitmapEditClassRec,  the 
complete  class  record.  Remember  that  since  the  actual  declaration  of  the  class  structure  is  in 
the  private  include  file,  the  application  cannot  access  class  structure  fields,  and  therefore  this 
pointer  is  opaque  to  the  application. 

5.3.8  A  Sample  Method 

Each  method  has  a  particular  job  to  do,  and  will  be  described  in  the  chapter  that  discusses 
that  job.  However,  we'll  describe  the  realize  method  now,  because  it  is  simple  and  dem 
onstrates  the  two  techniques  of  inheriting  for  self-contained  fields  that  were  described  in  Sec 
tion  5.3.5.2.  The  realize  method  is  responsible  for  creating  the  widget's  window,  and  vir 
tually  all  widgets  have  a  window.*  The  first  technique  is  to  inherit  wholesale  the  method 
defined  by  the  immediate  superclass.  The  superclass  may  have  its  own  realize  method,  or 
it  may  also  inherit  the  method  from  its  superclass,  and  so  on.  The  Core  widget's  realize 
method  creates  a  basic  window.f  In  your  subclasses  of  any  of  these  widgets,  you  can  inherit 
the  Core  realize  method  without  modification  by  initializing  the  realize  member  of 
the  Core  class  record  to  the  symbolic  constant  xtinheritRealize,  as  shown  in 
Example  5-12. 

BS 

Example  5-12.  BitmapEdit.c:  inheriting  a  self-contained  method 

BitmapEditClassRec  bitmapEditClassRec  =  { 

{  /*  Core  class  part  */ 


XtinheritRealize,   /*  realize  */ 


*  A  windowless  widget  is  called  a  gadget.  Some  versions  of  Xt  support  gadgets,  but  their  use  has  not  been  standard 
ized.  Furthermore,  they  were  created  to  reduce  the  overhead  of  widgets  by  removing  the  window  maintained  on  the 
server  side  and  replacing  it  with  client-side  code.  But  at  the  same  time,  the  X  Consortium  has  reduced  the  overhead 
of  windows  to  the  point  where  it  is  questionable  whether  gadgets  are  worthwhile.  Gadgets  are  described  in  Chapter 
12,  Menus,  Gadgets  and  Cascading  Pop  Ups. 

flf  you  have  the  source  code  for  Xt,  you  may  discover  that  the  Core  widget  is  actually  an  amalgamation  of  several 
other  superclasses  called  WindowObj,  RectObj,  and  so  on.  (You  might  also  notice  the  include  files  for  these  classes 
in  lusrlincludelXll.)  The  Core  widget  actually  inherits  the  realize  procedure  from  WindowObj.  These  classes 
are  an  implementation  detail  that  will  affect  you  only  if  you  want  to  look  in  some  of  these  superclasses  to  find  the 
code  that  implements  features  normally  attributed  to  Core.  From  application  code  or  widget  code,  it  is  always  safe  to 
assume  that  Core  is  the  top  of  the  class  tree.  For  gadgets  (discussed  in  Chapter  12),  you  need  to  know  more  about 
these  "hidden"  classes,  so  we'll  discuss  them  there. 
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Example  5-1 2.  BitmapEdit.c:  inheriting  a  self-contained  method  (continued) 


}, 

{ 
o, 

} 


/*  BitmapEdit  class  part  */ 

/*  dummy  field 


Xt  also  defines  symbolic  constants  for  inheriting  for  every  other  self-contained  method. 
They  all  begin  with  Xt  Inherit,  and  in  general  continue  with  the  capitalized  name  of  the 
method  field. 

An  important  part  of  the  process  of  creating  an  X  window  is  the  setting  of  window  attributes. 
Therefore,  a  brief  aside  on  window  attributes  is  necessary.  (You  can  skim  the  next  page  if 
you  are  already  familiar  with  them.) 

Window  attributes  are  basic  features  of  the  way  the  server  makes  windows  look  and  act. 
Window  attributes  can  also  be  changed  later  if  necessary,  but  the  realize  method  is  the 
place  to  set  them  initially.  The  Core  class  realize  method  sets  some  basic  window  attri 
butes  such  as  the  window  background  and  border  colors  or  patterns,  and  it  gets  these  values 
from  Core  resources.  Here  is  a  list  of  the  window  attributes  that  you  may  wish  to  set: 

Background          can  be  a  solid  color,  pattern,  or  transparent. 
Border  can  be  a  solid  color  or  pattern. 

Bit  Gravity  determines  how  partial  window  contents  are  preserved  when  a  window  is 

resized.  This  is  an  optimization  that  can  save  redrawing. 

Backing  Store  provides  hints  about  when  a  window's  contents  should  be  preserved  by  the 
server  even  when  the  window  is  obscured  or  unmapped.  This  is  useful  for 
widgets  that  are  very  time-consuming  to  redraw.  Not  all  servers  are  cap 
able  of  maintaining  a  backing  store.  Check  the  value  returned  from  the 
Xlib  DoesBackingStore  macro  to  determine  whether  this  feature  is 
supported  on  a  particular  screen  on  your  server. 

Saving  Under  provides  hints  about  whether  or  not  the  screen  area  beneath  a  window 
should  be  saved  while  a  window  such  as  a  pop-up  menu  is  in  place,  to  save 
obscured  windows  from  having  to  redraw  themselves  when  the  pop  up  is 
removed.  Not  all  servers  can  save  under  windows.  You  can  find  out 
whether  this  feature  is  supported  on  a  particular  screen  with  the  Xlib 
DoesSaveUnders  macro. 

Colormap  determines  which  virtual  colormap  should  be  used  for  this  window.  If 

your  widget  requires  a  lot  of  specific  colors,  for  example  to  draw  a  shaded 
image,  it  may  need  to  create  its  own  virtual  colormap.  In  that  case,  it 
would  set  this  attribute  to  the  ID  of  the  created  colormap.  For  more  infor 
mation  on  this,  see  Chapter  7,  Color,  in  Volume  One,  Xlib  Programming 
Manual. 
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Cursor  determines  which  cursor  should  be  displayed  when  the  pointer  is  in  this 

window.  You  must  create  this  cursor  before  setting  this  attribute.  This  can 
be  done  with  a  standard  type  converter,  as  described  in  Chapter  13,  Mis 
cellaneous  Toolkit  Programming  Techniques. 

It  may  clarify  the  picture  to  describe  the  features  that  window  attributes  do  not  affect.  Set 
ting  the  window  attributes  does  not  determine  a  window's  parent,  depth,  or  visual.  These  are 
all  set  when  a  window  is  created,  and  are  permanent.  The  window  attributes  are  also  not 
used  for  setting  the  size,  position,  or  border  width  of  a  widget  These  are  set  using  xtSet- 
Values.  Window  attributes  do  not  determine  how  graphics  requests  are  interpreted;  this  is 
the  job  of  the  graphics  context  (GC). 

Note  that  some  of  the  window  attributes  are  not  listed  here  because  they  should  not  be  set 
directly  by  widgets,  in  the  realize  method  or  anywhere  else.  These  include  the 
event_mask,  which  controls  which  events  are  sent  to  this  widget  Xt  itself  sets  this  win 
dow  attribute  based  on  the  translation  table.  Another  is  override_redirect,  which  is 
handled  by  the  Shell  widget 

If  you  want  to  set  additional  window  attributes  for  your  widget  you  will  use  the  second 
inheritance  scheme  used  for  self-contained  fields.  You  define  your  own  realize  method 
just  as  if  you  were  going  to  write  it  from  scratch,  but  then  you  call  the  superclass's  real 
ize  method  directly,  as  shown  in  Example  5-13. 

Example  5-13.  Inheriting  by  invoking  the  superclass  method  from  a  widget  method 
tdefine    superclass  (SwidgetClassRec) 

static   void  Realize (w,    valueMask,    attributes) 

Widget    w; 

XtValueMask  *valueMask; 

XSetWindowAttributes  *attributes; 

{ 

/*  this  is  already  set,  but  just  for  example  */ 

*valueMask  |=  CWBitGravity; 

attributes->bit_gravity  =  NorthWestGravity; 

/*  use  realize  method  from  superclass  */ 
(*superclass->core_class. realize)  {w,  valueMask,  attributes); 

} 

Xt  passes  to  the  realize  method  a  set  of  window  attributes  based  on  Core  instance  struc 
ture  values.  You  update  these  values  as  necessary,  and  then  call  the  superclass's  realize 
method,  as  shown. 

See  the  Xt  Realize?  roc  reference  page  in  Volume  Five,  X  Toolkit  Intrinsics  Reference 
Manual  to  find  out  the  default  settings  of  the  window  attributes  as  passed  into  the  realize 
method. 

You  may  wonder  what  happens  if  the  superclass  also  inherited  its  realize  method — does 
the  code  in  Example  5-13  crash  by  assuming  the  superclass  field  contains  a  function  pointer 
when  it  actually  contains  the  constant  xtlnheritRealize?  No.  When  the  class  is  ini 
tialized,  Xt  reconciles  all  the  inherited  methods  and  resets  the  class  record  fields  to  be  point 
ers  to  the  right  methods. 
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What  is  happening  behind  the  scenes  when  you  inherit  the  realize  method  is  that  the  Core 
realize  method  calls  the  Toolkit  function  Xt Great eWindow,  which  in  turn  calls  the 
Xlib  function  XCreateWindow.  You  may  need  to  call  the  Xlib  routine  yourself  in  the 
realize  method  if  you  want  to  use  a  visual  other  than  the  default.  See  the  reference  page 
for  XCreateWindow  in  Volume  Two,  Xlib  Reference  Manual,  and  Chapter  7,  Color,  in 
Volume  One,  Xlib  Programming  Manual,  for  details  on  depth,  visual,  and  the  issue  of  color 
in  general. 


5.4  The  Public  Header  File— BitmapEdit.h 

The  public  header  file  defines  the  aspects  of  the  widget  that  can  be  accessed  from  the  applica 
tion.  Public  include  files  tend  to  be  short  The  two  obligatory  features  of  the  BitmapEdit.h 
file  are: 

•  An  external  declaration  of  bitmapEditwidgetClass,  the  class  record  pointer  used 
by  applications  in  calls  to  xtCreateWidget  to  create  an  instance  of  this  widget  class. 

•  A  pointer  to  the  widget  instance  record,  in  this  case  BitmapEditwidget.  Xt  calls  all 
methods  and  actions  with  an  argument  of  type  widget.  To  access  any  of  the  fields  in 
the  instance  structure,  this  pointer  must  be  cast  to  type  BitmapEditwidget.  The  eas 
iest  way  to  do  this  is  to  declare  the  argument  of  the  method  as  type  BitmapEdit 
widget  (the  other  way  is  to  cast  in  an  assignment). 

If  your  resource  list  uses  xtN,  xtC,  or  xtR  constants  not  defined  in  <XlllStringDefs.h>, 
you  must  define  them  in  the  public  include  file. 

If  a  widget  offers  any  public  functions,  they  would  be  declared  extern  here  (and  actually 
defined  in  the  .c  file).  Public  functions  allow  the  application  to  read  or  change  certain  private 
data  in  certain  more  restricted  but  more  convenient  ways  than  is  possible  with  resources.  For 
example,  the  BitmapEdit  widget  provides  the  public  function  BitmapEditGetArray- 
String  that  applications  can  call  to  get  the  array  of  bits  currently  stored  as  private  data  in 
the  widget  (This  array  is  not  an  attribute  readable  with  XtGetValues  because  the  current 
implementation  does  not  allow  the  application  to  set  this  array.  A  future  iteration  could  add 
this  feature,  and  then  the  public  function  would  cease  to  be  necessary,  though  it  might  be 
kept  anyway  for  conveniece  and  backward  compatibility.) 

Example  5-14  shows  BitmapEdit's  public  header  file. 
Example  5-1 4.  BitmapEdit.h:  incidental  declarations 

lifndef  _ORABitmapEdit_h 
#define  _ORABitmapEdit_h 

/* 

*  BitmapEdit  Widget  public  include  file 
*/ 

/* 

*  This  include  not  needed  unless  the  application  includes 

*  Intrinsic. h  after  this  file.    Anyway,  it  doesn't  hurt. 
*/ 
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Example  5-1 4.  BitmapEdh.h:  incidental  declarations  (continued) 
tinclude    <Xll/Core.h> 


/*  Resources: 

*  Name 

* 

*  (from  RectObj) 

*  ancestorSensitive 


y 

width 
height 
borderWidth 
sensitive 

(from  Core) 

*  screen 

*  depth 

*  colormap 

*  background 

*  background? ixmap 

*  borderColor 

*  borderPixmap 


*  mappedWhenManaged 

*  translations 

*  accelerators 

* 

*  (from  BitmapEdit) 

*  foregroundPixel 

*  backgroundPixel 

*  callback 

*  cellSize 

*  pixmapWidth 

*  pixmapHeight 


Class 


RepType 


Screen 

Depth 

Colormap 

Backgroun 

Pixmap 

BorderColor 
BorderPixmap 

MappedWhen 
Managed 


Pointer 

Int 

Pointer 

pixel 

Pixmap 

pixel 
Pixmap 

Boolean 


Foreground  pixel 

Background  pixel 

Callback  Callback 

CellSize  int 

PixmapWidth  int 

PixmapHeight  int 


Default  Value 


Ancestor- 

Sensitive 

Position 

int 

0 

Position 

int 

0 

Dimension 
Dimension 
BorderWidth 

unsigned  int 
unsigned  int 

0 
0 

Sensitive 

XtCopyScreen 
XtCopyFromParent 
XtCopyFromParent 
White 
XtUnspecif ied- 

Pixmap 
Black 
XtUnspecif ied- 

Pixmap 
True 


Black 

White 

NULL 

30 

32 

32 


*  This  public  structure  is  used  as  call_data  to  the  callback. 

*  It  passes  the  x,  y  position  of  the  cell  toggled  (in  units  of 

*  cells,  not  pixels)  and  a  mode  flag  that  indicates  whether  the 

*  cell  was  turned  on  (1)  or  off  (0) . 
*/ 

typedef  struct  { 

int  mode; 

int  newx; 

int  newy; 
}  BitmapEditPointlnfo; 


#define  XtNcellSizelnPixels 
tdefine  XtNpixmapWidthlnCells 
fdefine  XtNpixmapHeightlnCells 
tdefine  XtNcurX 
tdefine  XtNcurY 
tdefine  XtNcellArray 


"cellSize InPixels" 

"pixmapWidthlnCells" 

"pixmapHeight InCel Is1 

"curX" 

"curY" 

"cellArray" 


Inside  a  Widget 


Example  5-1 4.  BitmapEdit.h:  incidental  declarations  (continued) 

#define  XtCCellSizelnPixels  "CellSizelnPixels" 

tdefine  XtCPixmapWidthlnCells  "PixmapWidthlnCells" 

tdefine  XtCPixmapHeightlnCells  "PixmapHeightlnCells" 

tdefine  XtCCurX  "CurX" 

#define  XtCCurY  "CurY" 

fdefine  XtCCellArray  "CellArray" 

extern  char  *BitmapEditGetArrayString ( ) ;  /*  w  */ 
/*  Widget  w;  */ 

/*  Class  record  constants  */ 

extern  WidgetClass  bitmapEditWidgetClass; 

typedef  struct  _BitmapEditClassRec  *BitmapEditWidgetClass; 
typedef  struct  _BitmapEditRec       *BitmapEditWidget ; 

fendif  /*  _ORABitmapEdit_h  */ 

/*  DON'T  ADD  STUFF  AFTER  THIS  #endif  */ 

It  is  a  good  idea  to  comment  the  types  of  the  resources  for  all  superclasses  as  shown  in 
Example  5-14.  Not  only  is  this  a  good  summary  for  you  of  all  the  resources  of  your  widget, 
but  it  allows  the  application  programmer  to  use  this  file  for  documentation  when  creating 
argument  lists. 


5.5  The  Process  of  Widget  Writing 

The  process  of  writing  a  widget  always  begins  with  the  same  steps.  They  are: 

•  Copy  all  three  files  of  the  widget  most  similar  to  the  one  you  intend  to  write;  pick  one 
that  has  many  methods  defined  so  that  you  don't  need  to  type  them  in.   (It's  easier  to 
delete  than  to  retype.) 

•  Globally  change  the  widget  class  name  in  the  files.  The  fastest  way  to  do  this  under  UNIX 
is  with  sed,  using  a  script  similar  to  the  following: 

s/BitmapEdit/AfewMime/g 
s/bi-tmapEdit/newName/q 

Place  this  script  in  the  file  sedscr,  and  run  the  command: 

spike%    sed  -f   sedscr   file  >  new file 
on  each  file.  (Or  write  a  simple  for  loop  to  run  it  on  multiple  files.) 

•  Start  from  the  top  of  the  .c  file,  and  begin  by  writing  the  resource  list.  While  writing  the 
resource  list,  you  may  need  to  edit  the  public  header  file  to  define  new  resource  names 
and  classes  (xtN  and  xtc  symbols).  While  writing  the  resource  list  (and  during  the 
entire  widget- writing  process),  you  will  also  need  to  edit  the  private  header  file  in  order 
to  add  and  remove  instance  part  structure  fields,  as  you  determine  a  need  for  them  while 
writing  methods  and  actions.  Later  you  will  probably  discover  additional  parameters  that 
you  want  to  define  as  resources. 
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•  Design  the  output  you  expect  your  widget  to  draw.  Your  instance  part  structure  fields 
must  hold  all  the  information  necessary  to  redraw  everything  when  the  window  is  expo 
sed — add  the  necessary  fields. 

•  Design  the  user  input  you  expect  your  widget  to  accept   Start  with  as  many  separate 
actions  as  you  can — one  for  each  distinguishable  user  input  idiom.    For  example, 
BitmapEdit  has  three  actions  for  changing  one  bitmap  cell:  DrawCell,  UndrawCell, 
and  ToggleCell.  Even  though  these  invoke  almost  identical  underlying  code,  it  is 
best  to  keep  them  as  separate  actions. 

•  Design  a  default  translation  table  to  have  these  actions  called  in  response  to  the  appropri 
ate  events.  Help  in  this  area  is  available  in  Section  7.1.2. 

•  Write  the  expose  method  and  actions.  Just  how  to  do  this  is  described  in  the  next  chap 
ter.  But  in  summary,  both  the  expose  method  and  actions  often  draw  into  the  widget. 
The  expose  method  must  always  be  able  to  redraw  what  the  actions  drew.  Therefore,  it 
usually  pays  to  have  common  elements  of  code  called  by  both  an  action  and  the  expose 
method.   Neither  the  action  nor  the  expose  method  pass  arguments  to  this  common 
code.  Instead,  the  actions  set  instance  variables  that  are  read  in  the  expose  method  or 
common  code.  The  instance  variables  act  as  global  variables  because  they  are  available 
almost  everywhere  in  the  widget  code. 

•  Add  parameters  that  allow  your  drawing  code  to  work  smoothly  in  any  size  window,  and 
add  a  resize  method  that  sets  these  parameters. 

•  Add  the  initialize  method  to  check  resource  values  that  might  have  been  user  sup 
plied  and  to  initialize  private  instance  variables. 

•  Add  the  set_values  method  to  check  application-supplied  resource  values  and  reset 
private  instance  variables  based  on  the  new  resource  values. 

•  Declare  the  methods  and  actions  you  have  defined,  near  the  top  of  the  .c  file. 

•  Enter  all  these  functions  and  tables  you  have  defined  into  the  class  structure  initialization. 

It  is  useful  to  have  a  simple  application  available  for  testing  your  widget  as  you  develop  it. 
One  that  simply  creates  the  widget  under  construction  and  provides  a  Quit  button  is  quite 
adequate.  Then  you  can  add  code  to  the  widget  incrementally,  assuring  at  each  step  that  the 
program  compiles,  links,  and  runs  without  error. 

As  this  list  implies,  it  is  a  good  idea  to  start  simply  and  complete  all  the  above  steps  for  a 
small  subset  of  the  features  you  eventually  want.  Once  you  have  a  working  widget  that  you 
can  test,  you  can  add  features  one  at  a  time  by  going  through  the  list  again.  If  instead  you 
attempt  to  write  an  ambitious  widget  in  one  pass,  you  will  spend  much  longer  debugging  it. 

Once  you  have  learned  how  to  write  methods  and  actions  in  the  next  chapter,  Basic  Widget 
Methods,  you  should  be  ready  to  write  a  simple  widget 


Inside  a  Widget 


5.6  Summary  of  Conventions 


The  naming  conventions  for  the  various  structure  declarations  in  the  widget  source  files  can 
be  confusing.  Table  5-3  summarizes  these  conventions,  using  the  BitmapEdit  widget  as  an 
example,  and  describes  where  each  type  is  used.  This  table  is  just  to  help  you  read  the  code. 
If  you  create  a  new  class  starting  from  an  existing  class,  and  globally  change  the  names  as 
described  above,  all  of  the  definitions  and  references  listed  here  will  already  be  done  for  you. 

Table  5-3.  Summary  ofXt  Structure  Name  Conventions 


Structure  Name 


Description 


BitmapEditClassPart 

BitmapEditClassRec 

bitmapEditClassRec 

BitmapEditPart 

BitmapEditRec 

_BitmapEditRec 

_BitmapEditClassRec 

BitmapEditWidget 

BitmapEditWidgetClass 
bitmapEditWidgetClass 


Partial  class  structure  typedef  (usually  dummy  field  only)  used 
for  defining  BitmapEditClassRec  in  P.h  file. 
Complete  class  structure  typedef,  declared  extern  in  P.h  file, 
used  for  initializing  class  structure  in  .c  file. 
Name  of  complete  class  structure  allocated  in  .c  file,  declared 
extern  in  P.h  file,  allocated  in  .c  file,  used  as  superclass  in 
class  record  initialization  of  subclasses  of  this  widget  (.c  file). 
Partial  instance  structure  typedef,  used  for  defining  Bitmap 
EditRec  in  P.h  file. 

Complete  instance  structure  typedef,  also  used  to  initialize 
widget_size  field  of  class  record  in  .c  file. 
Type  of  BitmapEditRec,  used  for  defining  BitmapEdit 
Widget  pointer  in  .h  file. 

Type     of     BitmapEditClassRec,     used     for     defining 
BitmapEditWidgetClass  pointer  in  .h  file. 
Pointer  to  BitmapEditRec   (complete  instance  structure), 
used  to  reference  instance  structure  fields  in  .c  file  (passed  as 
argument  to  methods). 

Pointer  to  _BitmapEditClassRec,  used  to  cast  bitmap 
EditClassRec  for  superclass  in  class  record  initialization  of 
subclasses  of  this  widget  (.c  file). 

Of  type  WidgetClass,  address  of  bitmapEditClass 
Rec,  used  in  XCreateWidget  calls  to  identify  class  to  be 
created. 
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This  chapter  describes  the  initialize,  expose,  set_values,  resize,  query geom 
etry,  and  destroy  methods.  It  explains  when  Xt  calls  each  method,  and 
describes  in  detail  what  should  be  in  each  of  these  methods.  Among  other 
things,  these  methods  prepare  for  and  do  the  drawing  of  graphics  that  appear 
in  a  widget.  This  chapter  describes  what  the  Toolkit  adds  to  the  graphics 
model  provided  by  Xlib,  but  does  not  describe  in  detail  how  to  draw  using  Xlib; 
this  topic  is  described  in  Chapters  5,  6  and  7  of  Volume  One,  Xlib  Program 
ming  Manual.  This  chapter  also  describes  how  to  write  action  routines  that 
work  in  the  widget  framework. 

In  This  Chapter: 

The  X  Graphics  Model  Inside  Widgets  166 

The  initialize  Method 166 

Creating  GCs 168 

The  expose  Method 170 

The  set_yalues  Method 174 

The  resize  Method 177 

The  query_geometry  Method  180 

The  destroy  Method 183 

Actions  in  the  Widget  Framework 184 


6 
Basic  Widget  Methods 


This  chapter  describes  the  initialize,  expose,  set_values,  resize, 
query_geometry,  and  destroy  methods.  These  are  the  methods  you  need  to  write  to 
make  a  functioning  widget  (although  destroy  is  optional).  The  thread  that  ties  most  of 
these  methods  together  is  that  they  have  a  role  in  drawing  graphics,  although  all  but  the 
expose  method  are  also  responsible  for  other  things.  We  will  describe  all  the  responsibili 
ties  of  these  methods,  but  focus  on  the  issues  involving  graphics  because  they  are  so  impor 
tant. 

Three  of  these  methods  are  called  by  Xt  in  response  to  application  function  calls: 

•  The  initialize  method  is  called  when  the  application  calls  xtCreateWidget. 

•  The  set_values  method  is  called  when  the  application  calls  xtSetValues. 

•  The  destroy  method  is  called  when  the  application  calls  xtDestroyWidget. 

A  fourth  method,  expose,  is  called  in  response  to  Expose  events,  which  occur  whenever 
part  or  all  of  a  widget's  window  becomes  newly  visible  on  the  screen.* 

When  the  parent  widget,  which  is  usually  a  geometry-managing  Composite  or  Constraint 
widget,  needs  to  resize  one  of  its  children,  it  may  call  the  child's  query_geometry 
method  to  find  the  child's  opinion  of  the  proposed  change.  Once  the  parent  has  actually 
resized  the  child,  Xt  calls  the  child's  resize  method,  which  is  responsible  for  calculating 
private  instance  variables,  so  that  the  child  is  prepared  to  redraw  itself  in  its  new  window 
size. 

Applications  that  use  the  Toolkit  should  do  all  their  drawing  in  widgets.  Although  it  is  pos 
sible  to  create  normal  X  windows  and  draw  into  them  from  the  application  code,  you  lose  the 
advantage  of  Xt's  event  dispatching,  event  filtering,  and  other  features.  It's  just  as  easy  to 
draw  in  a  widget,  and  it's  easier  to  add  processing  of  user  input  as  described  in  Chapter  7, 
Events,  Translations,  and  Accelerators. 


*Note  that  Expose  events  are  also  handled  through  the  translation  mechanism  like  any  other  event.  When  they  are 
present  in  the  translation  table,  the  action  registered  for  Expose  events  will  be  called  in  addition  to  the  expose 
method.  Widgets  do  not  normally  include  the  Expose  event  in  their  translation  table,  because  they  already  have  the 
expose  method.  Applications  might,  conceivably,  have  Expose  in  their  translation  table  to  add  drawing  capabil 
ity  to  a  widget,  although  it  is  difficult  to  calculate  where  to  do  this  drawing  from  the  application  since  the  widget's 
size  may  change. 
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6.1   The  X  Graphics  Model  Inside  Widgets 

Section  4.3.1  described  the  X  graphics  model  and  how  drawing  from  the  application  is 
accomplished.  In  summary,  the  process  consisted  of  creating  GCs  and  then  drawing  from  a 
function  that  Xt  calls  on  receipt  of  Expose  events.  Drawing  from  inside  a  widget  follows 
the  same  general  procedure,  but  the  code  is  organized  differently. 

Inside  a  widget,  you  normally  create  GCs  with  the  Xt  routine  xtGetGC  instead  of  the  Xlib 
routine  XCreateGC.  XtGetGC  is  similar  to  the  Xlib  routine  except  that  it  arranges  for  the 
sharing  of  GCs  among  widgets  within  an  application.  This  is  important  because  each  GC  has 
some  overhead  and  servers  can  achieve  better  performance  when  handling  fewer  GCs. 
Because  Xt  applications  often  have  many  instances  of  the  same  widget  class,  each  needing 
the  same  GC  characteristics  (unless  the  user  specifies  a  different  color  for  each  one),  Xt 
arranges  for  them  to  share  GCs  when  possible. 

Xt  organizes  GC  creation  and  drawing  into  separate  methods.  Setting  initial  values  for  the 
GC  and  creating  the  GC  is  done  in  the  initialize  method,  and  actual  drawing  is  done  in 
the  expose  method.  This  makes  it  very  easy  to  find  this  code  in  existing  widgets  and 
straightforward  to  write  this  code  for  new  widgets. 

Since  Xt  allows  resources  to  be  changed  during  program  execution  by  calling  xtSet- 
Values,  the  widget  code  must  be  prepared  to  change  the  GC  at  any  time  if  the  GC  compo 
nents  depend  on  resource  values.  The  set_values  method  calculates  the  new  values 
based  on  resource  changes  and  updates  the  appropriate  GCs. 

The  next  six  major  sections  discuss  the  code  needed  to  implement  the  initialize, 
expose,  set_values,  resize,  query_geometry,  and  destroy  methods. 


6.2  The  initialize  Method 


As  described  in  Section  5.3.5.2,  the  initialize  method  has  basically  one  function:  it 
sets  instance  structure  members  (also  called  instance  variables).*  This  job  has  two  parts: 
setting  the  initial  values  of  private  instance  variables,  and  checking  to  make  sure  that  the  val 
ues  of  the  public  instance  variables  are  valid  (since  they  are  user  configurable).  Since  the 
initialize  method  is  upward  chained  (defined  in  Section  5.3.5.2),  the  method  for  this 
class  needs  to  initialize  only  the  fields  present  in  the  instance  part  structure  for  this  class. 
The  exceptions  are  width  and  height.  Even  though  they  are  instance  variables  of  Core, 
they  need  to  be  checked  by  the  subclass,  because  only  this  class  knows  its  desired  initial  size. 

Example  6-1  shows  the  initialize  method  from  BitmapEdit 


*  As  described  in  Chapter  1 1 ,  Geometry  Management,  the  initialize  method  can  also  be  used  for  creating  child 
widgets  of  any  widget  This  is  a  way  of  getting  around  Xt's  geometry  management  scheme,  and  is  not  frequently 
done. 
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Example  6-1.  The  initialize  method 

/*  ARGSUSED  */ 

static  void 

Initialize (request,  new) 

BitmapEditWidget  request,  new; 

{ 

/* 

Alternate  method  of  casting: 

BitmapEditWidget  cw  =  (BitmapEditWidget)  new; 


Set  widget  to  initially  display  starting  at  top-left 

corner  of  bitmap 
*/ 

new->bitmapEdit .cur_x  =  0; 
new->bitmapEdit .cur_y  =  0; 

/* 

*  Check  instance  values  set  by  resources  that  may  be  invalid. 
*/ 

if  ( (new->bitmapEdit .pixmap_width_in_cells  <  1)  || 

(new->bitmapEdit .pixmap_height_in_cells  <  1))   { 
XtWarningC'BitmapEdit :  pixmapWidth  and/or  pixmapHeight  is  too  \ 

small  (using  10  x  10)."); 

new->bitmapEdit .pixmap_width_in_cells  =  10; 
new->bitmapEdit .pixmap_height_in_cells  =  10; 
} 

if  (new->bitmapEdit .cell_size  <  5)  { 

XtWarningC'BitmapEdit:  cellSize  is  too  small  (using  5)."); 

new->bitmapEdit .cell_size  =  5; 
} 

if  ( (new->bitmapEdit .cur_x  <  0)  ||   (new->bitmapEdit . cur_y  <  0) )  { 
XtWarningC'BitmapEdit:  cur_x  and  cur_y  must  be  non-negative  \ 

(using  0,  0) . ") ; 
new->bitmapEdit . cur_x  =  0; 
new->bitmapEdit .cur_y  =  0; 

} 

/* 

*  allocate  memory  to  store  array  of  cells 
*/ 

if  (new->bitmapEdit .cell  ==  NULL)/*unless  NULL, application  allocated*/ 
new->bitmapEdit .cell  = 

XtCalloc (new->bitmapEdit .pixmap_width_in_cells 
*  new->bitmapEdit .pixmap_height_in_cells, 
sizeof (char) ) ; 

new->bitmapEdit .pixmap_width_in_pixels  = 

new->bitmapEdit .pixmap_width_in_cells 

*  new->bitmapEdit . cell_size; 

new->bitmapEdit .pixmap_height_in_pixels  = 

new->bitmapEdit .pixmap_height_in_cells 

*  new->bitmapEdit .cell_size; 
if  (new->core .width  ==  0) 

new->core. width  =  (new->bitmapEdit .pixmap_width_in_pixels 
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Example  6-1.  The  initialize  method  (continued) 

>  300)     ? 

300  :  (new->bitmapEdit .pixmap_width_in_pixels) ; 
if  (riew->core . height  ==  0) 

new->core. height  =  (new->bitmapEdit .pixmap_height_in_pixels 

>  300)  ? 

300  :  (new->bitmapEdit .pixmap_height_in_pixels) ; 

CreateBigPixmap (new) ; 

GetDrawGC (new) ; 
GetUndrawGC (new) ; 
GetCopyGC (new) ; 

DrawIntoBigPixmap (new) ; 
} 

Even  though  the  specific  instance  variables  initialized  here  are  particular  to  BitmapEdit,  the 
techniques  are  common  to  all  initialize  methods.  Some  private  instance  variables, 
such  as  cur_x  and  cur_y,  do  not  depend  on  resource  settings  and  are  simply  initialized  to 
a  fixed  value.  Public  instance  variables  are  checked;  if  their  values  are  out  of  range,  xt- 
Warning  is  called  to  print  a  message  on  the  standard  output  and  they  are  instead  initialized 
to  a  fixed  value.  Some  private  instance  variables  are  set  based  on  public  instance  variables. 
GCs  are  the  most  common  example. 

6.2.1    Creating  GCs 

In  any  widget  that  does  drawing,  some  of  the  private  instance  variables  will  hold  the  IDs  of 
GCs  created  in  the  initialize  method.  These  variables  will  be  read  when  the  GCs  are 
needed  in  the  expose  method,  and  will  be  reset  if  necessary  in  the  set_values  method. 
Example  6-1  called  separate  routines,  GetDrawGC,  GetUndrawGC,  and  GetCopyGC  to 
create  the  GCs.  Example  6-2  shows  these  routines. 

A  program  prepares  for  creating  a  GC  by  setting  the  desired  characteristics  of  the  GC  into 
members  of  a  large  structure  called  XGCValues  (defined  by  Xlib),  and  specifying  which 
members  of  XGCValues  it  has  provided  by  setting  a  bitmask.  This  bitmask  is  made  by 
ORing  the  GC  mask  symbols  defined  in  <Xll/X.h>.  Each  bitmask  symbol  represents  a  mem 
ber  of  the  XGCValues  structure.  Every  GC  field  has  a  default  value,  so  only  those  values 
that  differ  from  the  default  need  to  be  set.  The  default  GC  values  are  discussed  in  Volume 
One,  Xlib  Programming  Manual. 

Widget  code  normally  creates  a  GC  with  the  xtGetGC  call,  not  the  Xlib  analogue 
XCreateGC.  XtGetGC  keeps  track  of  requests  to  get  GCs  by  all  the  widgets  in  an  appli 
cation,  and  creates  new  server  GCs  only  when  a  widget  requests  a  GC  with  different  values. 
In  other  words,  after  the  first  widget  creates  a  GC  with  XtGetGC,  any  subsequent  widget 
that  calls  XtGetGC  to  create  a  GC  with  the  same  values  will  get  the  same  GC,  not  a  new 
one.  Using  this  client-side  caching  also  reduces  the  number  of  requests  to  the  server. 

Xlib  provides  XChangeGC  to  change  the  values  in  an  existing  GC.  Xt  provides  no  analo 
gue.  Because  of  the  sharing  of  GCs  allocated  with  XtGetGC,  you  must  treat  them  as  read 
only.  If  you  don't,  you  may  confuse  or  break  other  widgets.  In  cases  where  your  widget 


168  X  Toolkit  Intrinsics  Programming  Manual 


creates  a  GC  that  needs  changing  in  such  a  way  that  it  is  impractical  to  create  a  new  GC  each 
time,  it  may  be  appropriate  to  use  the  Xlib  call  XCreateGC  instead  of  the  Xt  call  XtGet 
GC. 

BitmapEdit  must  use  XCreateGC  for  two  of  its  three  GCs  because  these  GCs  are  for  draw 
ing  into  pixmaps  of  depth  1,  while  XtGetGC  always  creates  GCs  for  drawing  into  windows 
or  pixmaps  of  the  default  depth  of  the  screen.  In  other  words,  XtGetGC  would  work  on  a 
monochrome  screen,  but  not  on  color.  However,  this  is  an  unusual  situation.  Most  widgets 
can  use  XtGetGC  exclusively. 

Example  6-2.  Creating  GCs  from  the  initialize  method 

static  void 
GetDrawGC (cw) 
BitmapEditWidget  cw; 

XGCValues  values; 

XtGCMask  mask  =  GCForeground  |  GCBackground  |  GCDashOffset  | 
GCDashList  I  GCLineStyle; 

/* 

*  Setting  foreground  and  background  to  1  and  0  looks  like  a 

*  kludge  but  isn't.   This  GC  is  used  for  drawing 

*  into  a  pixmap  of  depth  one.   Real  colors  are  applied  with  a 

*  separate  GC  when  the  pixmap  is  copied  into  the  window. 
*/ 

values . foreground  =  1; 

values .background  =  0; 

values. dashes  =  1; 

values .dash_off set  =  0; 

values. line_style  =  LineOnOf fDash; 

cw->bitmapEdit .draw_gc  =  XCreateGC (XtDisplay (cw) , 
cw->bitmapEdit ,big_picture,  mask,  Svalues)  ; 

static  void 
GetUndrawGC (cw) 
BitmapEditWidget  cw; 

XGCValues  values; 

XtGCMask  mask  =  GCForeground  I  GCBackground; 

/*  Looks  like  a  kludge  but  isn't — see  comment  in  GetDrawGC  */ 
values . foreground  =  0; 
values .background  =  1; 

cw->bitmapEdit.undraw_gc  =  XCreateGC (XtDisplay (cw) , 
cw->bitmapEdit ,big_picture,  mask,  svalues) ; 

static  void 
GetCopyGC (cw) 


BitmapEditWidget  cw; 

XGCValues  values 
XtGCMask  mask  = 

values.  foreground  =  cw->bitmapEdit  .  foreground 


XGCValues  values; 

XtGCMask  mask  =  GCForeground  |  GCBackground; 
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Example  6-2.  Creating  GCs  from  the  initialize  method  (continued) 

values .background   =   cw->core . background  j>ixel; 

/*    This    GC    is   the    same    depth   as    screen    */ 
cw->bitmapEdit .copy_gc   =   XtGetGC(cw,    mask,    Svalues) ; 
} 

As  shown  in  Example  6-2,  some  GC  components  are  set  based  on  other  instance  variables, 
and  some  are  just  hardcoded.  In  this  example,  the  foreground  pixel  value  (color)  in  the  GC  is 
set  to  be  the  value  of  the  foreground  instance  variable,  which  is  derived  from  a  resource 
of  BitmapEdiL  The  background  pixel  value  is  derived  from  a  resource  of  the  Core  widget. 
(Core  defines  a  background  resource  but  no  foreground.)  On  the  other  hand,  the 
line_style  member  of  XGCValues  is  set  to  LineOnOf  f  Dash  regardless  of  resource 
settings.  In  general,  you  hardcode  the  GC  components  that  you  don't  want  to  be  user  cus 
tomizable.  (All  these  instance  variables  are  defined  in  the  yourwidgetPart  structure 
defined  in  yourwidgetP.h.) 

Certain  GC  parameters  are  traditionally  handled  as  resources  rather  than  being  hardcoded. 
Colors  and  fonts  are  the  most  basic  examples.  In  the  X  Window  System  you  can't  use  a  color 
until  you  allocate  a  pixel  value  for  it,  and  you  can't  use  a  font  until  you  load  it.  The  code  that 
processes  resources  called  by  xt Initialize  automatically  allocates  and  loads  the  colors 
and  fonts  specified  as  resources,  and  sets  the  instance  variables  to  the  right  representation 
type  as  specified  in  the  resource  table.  Therefore,  it  is  actually  easier  to  provide  user  custom 
izability  than  to  convert  values  to  the  representation  types  required  to  hardcode  them. 

How  the  resource  conversion  process  works  will  be  described  in  more  detail  in  Chapter  9, 
Resource  Management  and  Type  Conversion.  To  decide  which  GC  settings  you  need  for  your 
application,  see  Chapter  5,  The  Graphics  Context,  in  Volume  One,  Xlib  Programming  Man 
ual. 


6.3  The  expose  Method 

The  expose  method  is  responsible  for  initially  drawing  into  a  widget's  window  and  for 
redrawing  the  window  every  time  a  part  of  the  window  becomes  exposed.  This  redrawing  is 
necessary  because  the  X  server  does  not  maintain  the  contents  of  windows  when  they  are 
obscured.  When  a  window  becomes  visible  again,  it  must  be  redrawn. 

The  expose  method  usually  needs  to  modify  its  drawing  based  on  the  geometry  of  the  win 
dow  and  other  instance  variables  set  in  other  methods.  For  example,  the  Label  widget  will 
left-justify,  center,  or  right-justify  its  text  according  to  the  XtN justify  resource,  and  the 
actual  position  to  draw  the  text  depends  on  the  widget's  current  size. 

Another  factor  to  consider  when  writing  the  expose  method  is  that  many  widgets  also  draw 
from  action  routines,  in  response  to  user  events.  For  example,  BitmapEdit  toggles  bitmap 
cells  in  action  routines.  The  expose  method  must  be  capable  of  redrawing  the  current  state 
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of  the  widget  at  any  time.  This  means  that  action  routines  usually  set  instance  variables 
when  they  draw  so  that  the  expose  method  can  read  these  instance  variables  and  draw  the 
right  thing. 

BitmapEdit  uses  a  slightly  unusual  exposure  handling  strategy.  Most  widgets  keep  track  of 
what  they  draw  in  some  form  of  arrays  or  display  lists.  When  they  need  to  redraw,  they  sim 
ply  replay  the  saved  drawing  commands  in  the  original  order  to  redraw  the  window.  For 
example,  BitmapEdit  keeps  track  of  the  state  of  each  bitmap  cell  in  a  character  array.  It 
could  easily  traverse  this  array  and  redraw  each  cell  that  is  set  in  the  array. 

However,  BitmapEdit  does  not  use  this  strategy.  In  order  to  improve  its  scrolling  perfor 
mance,  the  expose  method  copies  an  off-screen  pixmap  into  the  window  whenever 
redisplay  is  required.  The  actions  draw  into  this  off-screen  pixmap,  and  then  call  the 
expose  method  directly  to  have  the  pixmap  copied  to  the  window. 

The  expose  method  is  passed  an  event  that  contains  the  bounding  box  of  the  area  exposed. 
To  achieve  maximum  performance  it  copies  only  this  area  from  the  pixmap  to  the  window. 
The  BitmapEdit  actions  take  advantage  of  this,  too.  They  manufacture  an  artificial  event 
containing  the  bounding  box  of  the  cell  to  be  toggled,  and  pass  it  when  they  call  expose. 
This  causes  the  expose  method  to  copy  that  one  cell  that  was  just  updated  to  the  window. 

Example  6-3  shows  the  expose  method  from  the  BitmapEdit  widget. 
Example  6-3.  The  expose  method 

/*  ARGSUSED  */ 

static  void 
Redisplay (cw,  event) 
BitmapEditWidget  cw; 
XExposeEvent  *event; 
{ 

register  int  x,  y; 
unsigned  int  width,  height; 
if  (IXtlsRealized(cw) ) 
return; 

if  (event)  {   /*  called  from  btn-event  */ 

x  =  event->x; 

y  =  event->y; 

width  =  event->width; 

height  =   event->height; 
} 

else  {        /*  called  because  of  expose  */ 
x  =  0; 
y  =  0; 

width  =  cw->bitmapEdit .pixmap_width_in_pixels; 
height  =  cw-->bitmapEdit  .pixmap_height_in_pixels; 
} 

if  (Def aultDepthOf Screen (XtScreen (cw) )  ==  1) 

XCopyArea (XtDisplay (cw) ,  cw->bitmapEdit .big_picture, 
XtWindow(cw) , 

cw->bitmapEdit .copy_gc,  x  +  cw->bitmapEdit .cur_x,  y  + 
cw->bitmapEdit .cur_y,  width,  height,  x,  y)  ; 
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Example  6-3.  The  expose  method  (continued) 

else 

XCopyPlane (XtDisplay (cw) ,  cw->bitmapEdit .big_picture, 
XtWindow(cw) , 

cw->bitmapEdit .copy_gc,  x  +  cw->bitmapEdit .cur_x,  y  + 
cw->bitmapEdit .cur_y,  width,  height,  x,  y,  1); 

Note  that  the  expose  method  first  checks  to  see  that  the  widget  is  realized  using  xt- 
is Realized.  This  is  a  precaution  against  the  unlikely  event  that  an  instance  of  this 
widget  is  suddenly  destroyed  or  unrealized  by  an  application  while  Expose  events  are  still 
pending.  If  this  did  happen,  drawing  on  the  nonexistent  window  would  cause  an  X  protocol 
error. 

Next,  BitmapEdit's  expose  method  sets  the  rectangle  it  will  redraw  based  on  the  event 
passed  in  by  Xt.  We  also  call  this  method  directly  from  the  action  that  processes  button 
presses.  That  action  routine  creates  a  pseudo-event  to  pass  to  expose  to  describe  the  area 
to  be  drawn. 

If  the  compress_exposures  field  of  the  class  structure  is  initialized  to  TRUE,  as  it  is  in 
BitmapEdit,  Xt  automatically  merges  the  multiple  Expose  events  that  may  occur  because  of 
a  single  user  action  into  one  Expose  event.  In  this  case,  the  Expose  event  contains  the 
bounding  box  of  the  areas  exposed.  BitmapEdit  redraws  everything  in  this  bounding  box. 
For  widgets  that  are  very  time-consuming  to  redraw,  you  might  want  to  use  the  third  argu 
ment  of  the  expose  method,  which  is  a  region.  The  Region  type  is  opaquely  defined  by 
Xlib  (internally  a  linked  list  of  rectangles).  The  Region  passed  into  expose  describes  the 
union  of  all  the  areas  exposed  by  a  user  action.  You  can  use  this  region  to  clip  output  to  the 
exposed  region,  and  possibly  calculate  which  drawing  primitives  affect  this  area.  Xlib  pro 
vides  region  mathematics  routines  (such  as  XRectinRegion)  to  compare  the  regions  in 
which  your  widget  needs  to  draw  with  the  region  needing  redrawing.  If  certain  areas  do  not 
require  redrawing,  you  can  skip  the  code  that  redraws  them,  thereby  saving  valuable  time. 
However,  if  this  calculation  is  complicated,  its  cost/benefit  ratio  should  be  examined. 

Consider  the  arrangement  of  windows  shown  in  Figure  6-1.  Window  1  and  Window  3  are 
other  applications,  and  Widget  2  is  an  application  consisting  solely  of  our  widget 

Initially,  Window  3  is  on  top,  Window  1  is  behind  it,  and  Widget  2  is  hidden  completely 
behind  Window  1.  When  Window  1  is  lowered,  Widget  2  becomes  visible,  except  where  it  is 
still  overlapped  by  Window  3.  The  newly-exposed  area  can  be  described  by  two  rectangles; 
A  and  B.  If  compress_exposure  is  FALSE,  Widget  2's  expose  method  will  be  called 
twice,  and  passed  an  Expose  event  first  describing  Rectangle  A,  then  Rectangle  B.  But  if 
compress_exposure  is  TRUE,  Widget  2's  expose  method  will  be  called  just  once, 
passed  an  Expose  event  describing  the  bounding  box  of  all  the  original  Expose  events 
(which  would  be  the  entire  widget  in  this  case),  and  passed  a  Region  which  is  the  union  of 
the  rectangles  described  by  all  of  the  Expose  events.  The  region  argument  of  the 
expose  method  is  unused  unless  compress_exposures  is  TRUE. 

Each  of  these  exposure  handling  techniques  may  be  the  best  for  certain  widgets.  For  a 
widget  like  BitmapEdit,  any  of  the  three  methods  will  work,  but  the  bounding  box  method  is 
the  most  efficient  and  convenient.  For  a  complete  description  of  Expose  event  handling 
strategies,  see  Chapter  8,  Events,  in  Volume  One,  Xlib  Programming  Manual. 
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Figure  6-1.  compress_exposures:  2  rectangles  if  FALSE;  the  bounding  box  and  a  region  if 
TRUE 

The  remainder  of  BitmapEdit's  expose  method  shown  in  Example  6-3  consists  of  a  single 
Xlib  call  to  copy  from  a  pixmap  into  the  widget's  window.  As  described  in  Chapter  4,  An 
Example  Application,  BitmapEdit  makes  a  large  pixmap  that  is  one  plane  deep  and  draws  the 
current  bitmap  into  it.  When  needed  in  the  expose  method,  this  pixmap  just  has  to  be 
copied  into  the  window.  This  approach  was  chosen  for  its  simplicity.  When  scrollbars  are 
added,  the  widget  is  able  to  pan  around  in  the  large  bitmap  quickly  and  efficiently.  Note  that 
one  of  two  Xlib  routines  is  called  based  on  the  depth  of  the  screen.  This  is  because  XCopy- 
Area  is  slightly  more  efficient  than  XCopyPlane  and  should  be  used  when  running  on  a 
monochrome  screen. 
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Note  that  instance  variables  are  used  for  the  arguments  of  the  Xlib  routines  in  Example  6-3. 
Don't  worry  about  exactly  what  each  Xlib  routine  does  or  the  meaning  of  each  argument. 
See  the  reference  page  for  each  routine  in  Volume  Two,  Xlib  Reference  Manual,  when  you 
need  to  call  them  in  your  code. 

See  Chapters  5, 6,  and  7  in  Volume  One,  Xlib  Programming  Manual,  for  more  information  on 
the  GC,  drawing  graphics,  and  color,  respectively. 


6.4  The  set_vaiues  Method 

When  the  application  calls  xt  Set  Values  to  change  widget  resources  during  run  time,  Xt 
calls  the  set_values  method.  The  set_values  method  is  where  a  widget  responds  to 
changes  in  its  public  instance  variables.  It  should  validate  the  values  of  the  public  variables, 
and  recalculate  any  private  variables  that  depend  on  public  variables  that  have  changed. 

Example  6-4  shows  the  set_values  method  for  BitmapEdit. 
Example  6-4.  The  set_values  method 

/*  ARGSUSED  */ 

static  Boolean 

SetValues (current ,  request,  new) 

Widget  current,  request,  new; 

{ 

BitmapEditWidget  curcw  =  (BitmapEditWidget )  current; 

BitmapEditWidget  newcw  =  (BitmapEditWidget)  new; 

Boolean  do_redisplay  =  False; 

if  (curcw->bitmapEdit . foreground_pixel  != 

newcw->bitmapEdit . f oreground_pixel )  { 

XtReleaseGC (curcw,  curcw->bitmapEdit . copy_gc) ; 

GetCopyGC (newcw) ; 

do_redisplay  =  True; 
} 

if  ( (curcw->bitmapEdit .cur_x  !=  newcw->bitmapEdit .cur_x)  I  I 

(curcw->bitmapEdit .cur_y  !=  newcw->bitmapEdit . cur_y) )  { 
do_redisplay  =  True; 
} 

if  (curcw->bitmapEdit .pixmap_width_in_cells  != 

newcw->bitmapEdit .pixmap_width_in_cells)   { 
newcw->bitmapEdit .pixmap_width_in_cells  = 

curcw->bitmapEdit . pixmap_width_in_cells; 
XtWarning ("BitmapEdit:  pixmap_width_in_cells  cannot  be  set  by\ 

XtSetValues.\n") ; 
} 

if  (curcw->bitmapEdit .pixmap_height_in_cells  != 

newcw->bitmapEdit .pixmap_height_in_cells)  { 
newcw->bitmapEdit .pixmap_height_in_cells  = 

curcw->bitmapEdit . pixmap_height_in_cells; 

XtWarning ("BitmapEdit :  pixmap_height_in_cells  cannot  be  set  by\ 
XtSetValues.Xn") ; 
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Example  6-4.  The  set_values  method  (continued) 

/*    the    following   limitation    is    removed   later   on:    */ 
if    (curcw->bitmapEdit .cell_size_in_pixels    != 

newcw->bitmapEdit  .cell_size_in__pixels)     { 
newcw->bitmapEdit .cell_size_in_pixels   = 

curcw->bitmapEdit . cell_size_in_pixels; 

XtWarningC'BitmapEdit :    cell_size_in_pixels   cannot   be   set   by\ 
XtSetValuesAn")  ; 


return   do_redisplay; 

The  set_values  method  is  called  with  three  copies  of  the  widget's  instance  structure  as 
arguments:  current,  request,  and  new.  The  current  copy  includes  the  current  set 
tings  of  the  instance  variables,  and  request  includes  the  settings  made  through  xtSet- 
Values  but  not  yet  changed  by  the  superclasses'  set_values  methods.  The  new  copy 
is  the  same  as  request  except  that  it  has  already  been  processed  by  the  set_yalues 
methods  of  all  superclasses. 

For  each  public  variable,  set_values  compares  the  current  value  and  the  new  value,  and 
if  they  are  different,  validates  the  new  value  or  changes  any  private  values  that  depend  on  it. 
The  new  copy  is  the  only  one  that  the  method  changes;  request  and  current  are  only 
for  reference.  As  in  the  initialize  method,  you  have  to  deal  only  with  the  instance  vari 
ables  for  your  subclass,  and  perhaps  with  width  and  height,  because  the  set_values 
method  is  downward  chained.  Superclass  set_values  methods  take  care  of  setting  all  the 
superclass  instance  fields.  However,  if  desired,  you  can  change  superclass  fields  in  your 
method  since  it  is  called  last.  For  example,  this  might  be  useful  if  your  class  has  different  cri 
teria  for  determining  valid  values  or  dependencies. 

The  request  copy  of  the  instance  variables  is  used  only  if  your  class  needs  to  decide 
between  a  superclass  setting  and  your  widget's  setting;  disagreements  about  this  usually 
occur  over  the  size  of  the  widget  For  more  information  on  when  to  use  request,  see  the 
reference  page  for  xtSetValuesFunc  in  Volume  Five,  X  Toolkit  Intrinsics  Reference 
Manual. 

It  is  also  important  to  notice  that  the  set_values  method,  if  it  exists  at  all  (that  is,  ifj.it  is 
not  specified  as  NULL  in  the  class  structure),  must  return  TRUE  or  FALSE  to  indicate  whether 
the  changes  made  to  the  state  variables  require  the  widget  to  be  redrawn.  If  it  is  TRUE  for  this 
class  or  any  superclass,  Xt  calls  the  Xlib  routine  XClearArea  with  the  exposures  argu 
ment  set  to  TRUE  (to  force  the  background  of  the  widget  to  be  redrawn,  which  normally 
occurs  only  after  Expose  events),  and  then  Xt  calls  the  expose  method.  In  other  words, 
you  should  make  set_values  return  TRUE  whenever  the  changes  to  the  instance  variables 
will  change  what  is  drawn  in  the  widget. 

Note,  however,  that  set_values  should  not  return  TRUE  if  width  and  height  change, 
because  the  X  server  automatically  generates  Expose  events  for  a  window  when  it  is 
resized.  If  you  do  return  TRUE  in  this  case,  your  expose  method  will  be  called  twice. 
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Since  the  application  may  call  XtSetValues  before  the  widget  is  realized,  it  is  important 
not  to  assume  in  the  set_values  method  that  the  widget  has  a  window.  In  other  words, 
the  code  must  use  xt  isRealized  to  check  whether  the  widget  is  realized  before  using  the 
xt window  macro,  such  as  in  a  call  to  set  window  attributes. 

As  mentioned  earlier,  some  of  the  private  variables  are  usually  GCs.  Whenever  the  public 
variable  for  a  color  or  font  is  changed  through  XtSetValues,  a  GC  also  has  to  be 
changed.  This  is  an  example  of  a  private  variable  depending  on  a  public  one.  GCs  allocated 
with  xtGetGC  should  not  be  changed  since  they  may  be  shared  by  other  widgets.  There 
fore,  the  normal  response  to  a  change  in  one  of  the  resources  on  which  a  GC  depends  is  to 
release  the  GC  with  XtReleaseGC  and  request  a  new  one  with  XtGetGC.* 

If  some  of  your  widget's  GCs  are  unlikely  to  be  shared  by  other  widget  instances  in  an  appli 
cation  (either  because  each  instance  will  use  different  values  for  the  GC  components  or  there 
will  be  only  one  instance),  and  the  widget  needs  to  be  able  to  make  changes  to  them,  and  the 
changes  are  not  predictable  enough  or  few  enough  to  reasonably  create  a  GC  for  each  varia 
tion,  then  the  xtGetGC/xtReleaseGC  approach  is  not  ideal.  What  happens  in  this  situa 
tion  is  that  XtGetGC  creates  a  new  GC  and  XtReleaseGC  frees  the  old  GC  every  time  a 
change  is  made,  even  if  the  changes  are  small.  It  is  more  efficient  in  this  situation  to  change 
the  affected  values  in  the  existing  GC.  But  this  can  be  done  only  with  an  Xlib  routine — there 
is  no  Toolkit  routine  for  changing  a  GC.  To  implement  this  approach,  you  create,  modify, 
and  free  the  unusual  GC  using  Xlib  routines  only.  You  call  XCreateGC  in  the  initial 
ize  method  to  create  the  GC,  XChangeGC  in  the  set_yalues  method  to  change  the 
GC,  and  XFreeGC  in  the  destroy  method  to  free  the  GC.  All  of  these  Xlib  routines  are 
described  in  Chapter  5,  The  Graphics  Context,  in  Volume  One,  Xlib  Programming  Manual. 

XtGetGC  always  creates  a  GC  that  can  only  be  used  on  drawables  (windows  and  pixmaps) 
of  the  default  depth  of  the  screen.  Drawing  into  a  pixmap  of  depth  one  using  a  GC  created 
with  XtGetGC  works  on  a  monochrome  display,  but  usually  does  not  work  on  a  color  dis 
play.  (The  depth  is  the  number  of  bits  per  pixel  used  to  represent  colors  on  the  screen.)  This 
is  another  situation  in  which  you  will  need  to  call  XCreateGC  instead  of  XtGetGC. 

Note  also  that  BitmapEdit  does  not  allow  three  of  its  resources  to  be  changed  by  XtSet 
Values;  they  can  be  set  only  until  the  widget  is  created.  To  disallow  changes  to  a  resource, 
the  set_values  method  must  actively  set  the  value  in  the  new  widget  (newcw)  to  the 
value  in  the  current  widget  (curcw),  wiping  out  the  setting  made  through  XtSetValues. 
It  is  also  advisable  that  the  widget  print  a  message  describing  that  the  resource  cannot  be  set 
through  XtSetValues. 

The  xtwarning  call  used  in  the  example  is  simply  an  alternative  to  calling  fprintf .  It 
helps  to  make  all  error  messages  uniform,  and  is  described  in  Chapter  13,  Miscellaneous 
Toolkit  Programming  Techniques. 


*In  Release  2,  the  function  to  release  a  GC  was  called  XtDestroyGC. 
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6.5  The  resize  Method 


When  a  widget  is  used  in  an  application,  it  is  created  with  a  parent  that  will  manage  its  geom 
etry.  Depending  on  the  layout  policy  of  this  parent  widget  in  the  application,  the  widget's 
window  may  change  size  when  the  application  is  resized.*  Most  widgets  need  to  recalculate 
the  position  and  size  of  their  graphics  when  their  window  changes  size.  This  is  the  job  of  the 
resize  method. 

The  resize  method  is  passed  only  one  argument,  the  widget  instance  structure  pointer 
(widget  ID).  This  structure  contains  the  new  position,  size,  and  border  width  of  the  widget's 
window.  The  method  changes  any  instance  part  fields  that  depend  on  the  size  or  position  of 
the  widget  When  the  resize  method  returns,  Xt  calls  the  expose  method,  regardless  of 
whether  or  not  the  contents  need  redrawing.  (It  is  a  basic  characteristic  of  the  X  server  that  it 
generates  Expose  events  when  a  window  is  resized.) 

A  Label  widget  whose  text  is  centered  would  reset  the  starting  position  of  its  text  in  the 
resize  method. 

In  some  widgets,  it  takes  some  thought  to  determine  the  correct  response  to  resizing.  Take 
BitmapEdit,  for  example.  BitmapEdit  is  designed  to  be  able  to  show  only  a  portion  of  the  bit 
map,  so  that  scrollbars  can  pan  around  in  the  complete  bitmap.  When  the  application  is 
resized,  should  BitmapEdit  show  more  cells  or  increase  the  cell  size?  Up  to  the  point  where 
the  entire  bitmap  is  shown,  it  is  easier  to  increase  the  number  of  cells  shown.  When  Bitmap- 
Edit  is  resized  larger  than  necessary  to  show  the  entire  bitmap,  it  should  probably  increase 
the  cell  size.  We  will  use  this  strategy  in  the  resize  method  of  the  BitmapEdit  widget, 
which  is  shown  in  Example  6-5. 

This  resize  strategy  does  have  one  problem.  It  never  reduces  the  cell  size.  This  is  not  a  seri 
ous  problem  because  BitmapEdit  has  a  resource  that  controls  the  cell  size.  Therefore,  the 
application  that  uses  this  widget  could  provide  a  user  interface  for  setting  the  cell  size  if  the 
application  writer  was  concerned  about  this  problem. 

Example  6-5.  BitmapEdit:  the  resize  method 

/*  ARGSUSED  */ 
static  void 
Resize (cw) 

BitmapEditWidget  cw; 
{ 

/* 

*  resize  does  nothing  unless  new  size  is  bigger 

*  than  entire  pixmap 
*/ 

if  ( (cw->core .width  > 

cw->bitmapEdit .pixmap_width_in_pixels)    && 
(cw->core .height    > 


*Also  note  that  the  application  may  be  resized  when  it  is  first  mapped  on  the  screen,  when  the  user  sizes  the  rubber- 
band  outline  of  the  application  provided  by  most  window  managers.  (You  may  not  think  of  this  as  resizing,  but  it  is.) 
When  this  happens,  the  application  has  already  created  its  widgets  and  the  widgets  have  created  windows.  Therefore, 
the  re  si  ze  method  of  a  widget  will  be  called  if  its  parent  widget  is  forced  to  resize  it. 
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Example  6-5.  BitmapEdit:  the  resize  method  (continued) 

cw->bitmapEdit .pixmap  height  in  oixels) )  { 
/* 

*  Calculate  the  maximum  cell  size  that  will  allow 

*  the  entire  bitmap  to  be  displayed. 
*/ 

Dimension  w_temp_cell_size_in_pixels, 

h_t emp_c e 1 l_s i z e_i n_p i xe 1 s ; 
Dimension  new_cell_size_in_pixels; 

w_temp_cell_size_in_pixels  =  cw->core .width  / 
cw->bitmapEdit . pixmap_width_in_cells; 

h_temp_cell_size_in_pixels  =  cw->core .height  / 
cw->bitmapEdit . pixmap_height_in_cells; 

if  (w_temp_cell_size_in_pixels  < 

h_temp_cell_size_in_pixels) 
new_cell_size_in_pixels  = 

w_temp_cell_size_in_pixels; 
else 

new_cell_size__in_pixels  = 

h_temp_cell_size_in_pixels; 

/*  if  size  change  mandates  a  new  pixmap,  make  one  */ 
if  (new_cell_size_in_pixels  !=  cw-> 

bitmapEdit . cell_size_in_pixels)  { 
ChangeCellSize (cw,  new_cell_size_in_pixels) ; 

} 


static  void 

ChangeCellSize (cw,  new_cell_size) 

BitmapEditWidget  cw; 

int  new_cell_size; 

{ 

int  x,  y; 

cw->bitmapEdit .cell_size_in_pixels  =  new_cell_size; 

/*  recalculate  variables  based  on  cell  size  */ 

cw->bitmapEdit  .pixmap_width_in_jpixels   = 

cw->bitmapEdit .pixmap_width_in_cells  * 
cw->bitmapEdit . cell_size_in_pixels; 

cw->bitmapEdit .pixmap_height_in_pixels  = 

cw->bitmapEdit .pixmap_height_in_cells  * 
cw->bitmapEdit . cell_size_in_pixels; 

/*  destroy  old  and  create  new  pixmap  of  correct  size  */ 
XFreePixmap (XtDisplay (cw) ,  cw->bitmapEdit .big_picture) ; 
CreateBigPixmap (cw) ; 

/*  draw  lines  into  new  pixmap  */ 
DrawIntoBigPixmap (cw) ; 

/*  draw  current  cell  array  into  pixmap  */ 
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Example  6-5.  BitmapEdit:  the  resize  method  (continued) 

for    (x   =    0;    x   <   cw-> 

bitmapEdit .pixmap_width_in_cells;  x++)  { 
for  (y  =  0;  y  <  cw-> 

bitmapEdit .pixmap_height_in_cells;  y++)  { 
if  (cw->bitmapEdit .cell [x  + 

(y  *  cw->bitmapEdit .pixmap_width_in_cells) ]  ==  DRAWN) 

DoCell(cw,  x,  y,  cw->bitmapEdit .draw_gc) ; 
else 

DoCelKcw,  x,  y,  cw->bitmapEdit  .undraw_gc)  ; 


static  void 

DoCell  (w,  x,  y,  gc) 

BitmapEditWidget  w; 

int  x,  y; 

GC  gc; 

{ 

/*   draw   or   undraw  a   cell    */ 

XFillRectangle  (XtDisplay  (w)  ,    w->bitmapEdit  .bigjpicture,    gc, 
w->bitmapEdit  .cell_size_in_pixels    *    x   +   2, 
w->bitmapEdit  .cell_size_in_pixels    *    y   +   2, 
(unsigned   int)  w->bitmapEdit  .  cell_size_in_pixels    -   3, 
(unsigned    int)  w->bitmapEdit  .  cell_size_in_pixels    -   3) 


Because  of  the  two-phase  resize  strategy  used  by  BitmapEdit,  and  because  BitmapEdit  uses  a 
pixmap  in  its  repaint  strategy,  this  resize  method  is  more  complicated  than  most.  When 
the  widget  is  resized  larger  that  necessary  to  show  the  entire  bitmap  in  the  current 
cell_size,  it  destroys  the  current  pixmap  and  creates  a  new  one.  Since  this  should  not 
happen  very  often  and  because  resizing  does  not  require  extremely  fast  response,  the  time  it 
takes  to  recreate  the  pixmap  and  draw  into  it  is  acceptable. 

One  difficulty  in  writing  the  resize  method  is  that  you  do  not  have  access  to  the  old  size  or 
position  of  the  window.  The  widget  instance  structure  passed  in  has  already  been  updated 
with  the  current  size  and  position.  If  you  need  the  old  information,  you  can  cache  the  old 
size  in  an  instance  part  field,  set  first  in  the  initialize  method,  and  again  at  the  end  of 
the  resize  method. 

It  is  also  important  to  note  that  the  resize  method  is  not  allowed  to  request  that  the  parent 
resize  the  widget  again  to  get  a  better  size.  (How  to  suggest  properly  to  the  parent  that  your 
widget  be  resized  is  described  in  Chapter  11,  Geometry  Management.) 

In  the  set_values  method  shown  in  Section  6.4,  changes  to  BitmapEdit's  xtNcell- 
SizelnPixels  resource  were  not  allowed.  Now  that  we  have  a  working  ChangeCell- 
Size  function,  a  small  change  to  the  code  that  handles  cell  size  changes  in  set_values 
will  allow  the  cell  size  to  be  changed  at  any  time.  The  new  code  is  shown  in  Example  6-6. 
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Example  6-6.  BftmapEdit:  modification  to  set_values  method  to  support  changing  cell  size 

if  (curcw->bitmapEdit .cell_size_in_pixels  != 
newcw->bitmapEdit . cell_size_in_pixels)  { 

ChangeCellSize (curcw,  newcw->bitmapEdit .cell_size_in_pixels) ; 
do_redisplay  =  TRUE; 


6.6  The  query_geometry  Method 

When  your  widget  is  used  in  an  application,  its  parent  widget  will  be  a  composite  or  con 
straint  widget  that  manages  its  size  and  position.  Parent  widgets  need  to  know  the  preferred 
size  of  a  widget  so  they  can  make  good  decisions  about  the  size  of  each  child.  The 
query_geometry  method  is  called  when  the  parent  is  about  to  make  a  size  change  to 
some  of  its  children  but  is  not  yet  sure  which  ones  and  by  how  much.  (How  geometry  man 
agement  works  is  described  in  Chapter  11,  Geometry  Management.  For  now,  we  are  concen 
trating  on  what  you  need  to  do  to  write  a  simple  widget.) 

If  your  widget  specifies  NULL  in  the  class  structure  for  the  query_geomet  ry  method,  the 
parent  will  be  told  that  your  widget's  current  geometry  is  its  preferred  geometry.  This  is 
often  wrong  information.  For  example,  if  your  widget  has  already  been  resized  to  be  one- 
pixel-by-one-pixel  because  the  user  has  resized  an  application  to  be  very  small,  the  parent 
would  receive  the  message  that  your  widget  prefers  to  be  that  small.  When  the  application  is 
resized  to  be  larger  again,  the  parent  will  have  no  information  on  which  to  base  its  resizing 
decisions.  Even  if  your  widget  has  no  particular  preference  for  size,  it  is  a  good  idea  to  spec 
ify  the  widget's  default  size  in  query_geometry.  Then,  at  least,  the  parent  has  a  ballpark 
figure  for  typical  sizes  for  your  widget.  The  parent  could  at  least  find  out  that  BitmapEdit  is 
intended  to  be  larger  than  a  Label  widget. 

The  query_geometry  method  is  passed  pointers  to  two  copies  of  the  XtWidget- 
Geometry  structure,  one  containing  the  parent's  intended  size  for  your  widget,  and  the 
other  to  contain  your  reply  to  the  parent's  suggestion.  The  xt  widget  Geometry  structure 
is  shown  in  Example  6-7. 

5s;;?s 

Example  6-7.  The  XtWidgetGeometry  structure 

typedef  struct  { 

XtGeometryMask  request_mode; 

Position  x,  y; 

Dimension  width,  height; 

Dimension  border_width; 

Widget  sibling; 

int  stack_mode; 
}  XtWidgetGeometry; 

The  request_mode  field  is  a  mask  that  indicates  which  other  fields  in  the  structure  are  set 
It  is  a  bitwise  OR  of  any  or  all  of  the  symbolic  constants  shown  in  Table  6- 1 . 
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Table  6-1.  XtWidgetGeometry  request_mode  Symbols 


Symbol 


Description 


cwx 
CWY 

CWWidth 
CWHeight 
CWBorderWidth 
CWSibling 

CWStackMode 


The  x  coordinate  of  the  widget's  top  left  corner  is  specified 

The  y  coordinate  of  the  widget's  top  left  corner  is  specified 

The  widget's  width  is  specified 

The  widget's  height  is  specified 

The  widget's  borderwidth  is  specified 

A  sibling  widget  is  specified,  relative  to  which  this  widget's  stacking 

order  should  be  determined 

A  stack_mode  value  is  present,  specifying  how  this  widget  should 

be  stacked  relative  to  the  widget  identified  as  sibling 


The  sibling  and  stack_mode  fields  are  used  together  to  indicate  where  in  the  stacking 
order  of  its  siblings  your  widget  will  be  placed.  The  symbols  for  stack_mode  are  Above 
Below,  Toplf ,  Bottomlf ,  Opposite,  and  XtSMDontChange.  (These  symbols  are 
used  singly,  not  combined  with  OR.)  Their  meanings  are  summarized  in  Table  6-2. 

Table  6-2.  XtWidgetGeometry  stack_mode  Symbols 


Stacking  Flag 


Position 


Above 


Below 


Toplf 


Bottomlf 


Opposite 


XtSMDontChange 


vr  is  placed  just  above  sibling.  If  no  sibling  is  specified,  w  is 
placed  at  the  top  of  the  stack. 

w  is  placed  just  below  sibling.  If  no  sibling  is  specified,  w  is 
placed  at  the  bottom  of  the  stack. 

If  sibling  obscures  w,  then  w  is  placed  at  the  top  of  the  stack.  If  no 
sibling  is  specified,  then  if  any  sibling  obscures  w,  w  is  placed  at 
the  top  of  the  stack. 

If  w  obscures  sibling,  then  w  is  placed  at  the  bottom  of  the  stack.  If 
no  sibling  is  specified,  then  if  w  obscures  any  sibling,  wis  placed  at 
the  bottom  of  the  stack. 

If  sibling  occludes  w,  w  is  placed  at  the  top  of  the  stack.  If  w 
occludes  sibling,  w  is  placed  at  the  bottom  of  the  stack.  If  no 
sibling  is  specified,  then  if  any  sibling  occludes  w,  w  is  placed  at 
the  top  of  the  stack,  or  if  w  occludes  any  sibling,  w  is  placed  at  the  bot 
tom  of  the  stack. 

Current  position  in  stacking  order  is  maintained. 


Note  that  Xt's  handling  of  stacking  order  is  currently  imcomplete,  and  these  symbols  might 
not  be  honored. 


Basic  Widget  Methods 


One  more  issue  about  the  query_geometry  method  must  be  raised  before  showing  an 
example;  the  method's  return  value.  The  query_geometry  method  must  return  one  of 
the  three  enum  values  Xt  Geometry  Yes,  XtGeometryAlmost,  or  XtGeometryNo. 
xtGeometryResult  is  an  enum  name,  and  it  is  the  returned  type  of 
query_geometry. 

•  If  the  proposed  geometry  is  acceptable   without  modification,  query_geometry 
returns  Xt  Geometry  Yes. 

•  If  the  proposed  geometry  is  not  acceptable,  your  widget  returns  XtGeometryAlmost 
and  sets  its  suggested  changes  to  the  proposed  geometry  back  in  the  reply  structure. 

•  If  the  proposed  geometry  is  the  same  as  the  current  geometry,  query_geometry 
returns  XtGeometryNo.    This  symbol  is  slightly  misleading — think  of  it  as  xt- 
GeometryNoChange  (a  symbol  that  is  not  defined).  The  symbol  is  XtGeometryNo 
because  all  three  of  these  symbols  are  used  in  another  context  within  composite  and  con 
straint  widgets,  as  is  described  in  Chapter  11,  Geometry  Management. 

Note  that,  in  all  three  cases,  query_geometry  must  set  any  fields  in  the  reply  structure 
that  it  potentially  cares  about,  even  if  it  is  only  accepting  the  proposed  geometry. 

Example  6-8  shows  the  query_geometry  method  from  BitmapEdit.  All  widgets  should 
have  at  least  this  code  in  the  method,  substituting  their  initial  size,  or  their  current  preferred 
size  if  known.  (For  example,  a  Label  widget  would  set  its  preferred  size  based  on  the  width 
and  height  of  the  current  string.) 

Example  6-8.  BitmapEdit:  the  query_geometry  method 

static   XtGeometryResult   QueryGeometry (w,    proposed,    answer) 
BitmapEditWidget    w; 

XtWidgetGeometry    *proposed,     *answer; 
{ 

answer->request_mode    =   CWWidth    |    CWHeight; 

/*    initial    width   and   height    */ 

answer->width   =    (w->bitmapEdit . pixmap_width_in_pixels    >    300) 

?    300    :    w->bitmapEdit .pixmap_width_in_pixels; 
answer->height    =    (w->bitmapEdit .pixmap_height_in_pixels    >    300) 

?   300    :    w->bitmapEdit .pixmap_height_in_pixels; 

if    (       ( (proposed->request_mode    &     (CWWidth    |    CWHeight)) 
==    (CWWidth    |    CWHeight))    && 
proposed->width   ==   answer->width   && 
proposed->height    ==    answer->height ) 
return   XtGeometryYes; 
else    if    (answer->width   ==   w->core .width   && 

answer->height   ==   w->core .height) 
return   XtGeometryNo; 
else 

return   XtGeometryAlmost; 
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6.7  The  destroy  Method 

When  a  widget  is  destroyed  by  the  application,  its  destroy  methods  are  invoked  in  sub 
class  to  superclass  order.  Therefore,  the  destroy  method  for  any  given  class  need  free 
only  memory  allocated  by  itself;  it  need  not  worry  about  memory  allocated  by  superclasses. 

Any  server  resources  created  by  Xt  (such  as  GCs  requested  through  xtGetGC)  should  be 
freed  in  the  destroy  method.  In  addition,  if  you  called  any  Xlib  routines,  such  as 
XCreateGC,  that  allocate  server-  or  client-side  resources,  be  sure  to  free  them  here. 
BitmapEdit  creates  pixmaps  for  use  in  the  drawing  process,  so  it  must  free  them.  It  must  also 
free  the  GCs  it  allocated  with  XCreateGC. 

If  this  is  not  done,  then  the  server  resources  allocated  for  the  widget  will  not  be  freed  until 
the  application  exits.  This  is  not  a  fatal  problem.  It  matters  only  in  applications  that  destroy 
widgets  and  then  continue  running  for  a  while  before  they  exit,  which  is  unusual.  Example 
6-9  shows  the  destroy  method  code  from  the  BitmapEdit  widget.  It  frees  the  pixmaps 
created  in  the  initialize  method  shown  in  Example  6-1  above. 

Example  6-9.  The  destroy  method 

static  void 
Destroy (cw) 
BitmapEditWidget  cw; 

{ 

if  (cw->bitmapEdit .big_picture) 

XFreePixmap (XtDisplay (cw) ,  cw->bitmapEdit .big_picture) ; 

if  (cw->bitmapEdit .draw_gc) 

XFreeGC (XtDisplay (cw) ,  cw->bitmapEdit .draw_gc) ; 

if  (cw->bitmapEdit .undraw_gc) 

XFreeGC (XtDisplay (cw) ,  cw->bitmapEdit .undraw_gc) ; 

if  (cw->bitmapEdit .copy_gc) 

XtReleaseGC (cw,  cw->bitmapEdit .copy_gc) ; 

/*  This  memory  allocated  with  XtCalloc  in  initialize  method  */ 
XtFree (cw->bitmapEdit .cell)  ; 

11  } 

If  your  widget  allocated  memory  for  any  of  its  instance  variables  (or  other  global  variables) 
using  the  Toolkit  routines  xtMalloc  or  XtCalloc  (which  operate  just  like  the  C  library 
but  add  error  checking),  then  it  should  free  that  memory  here  with  XtFree. 

If  your  widget  called  xtAddE  vent  Handler  or  xtAddTimeOut,  then  you  should  call 
XtRemoveEventHandler  and  XtRemoveTimeOut,  respectively  (here  these  routines 
are  described  in  Chapter  8,  More  Input  Techniques). 
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6.8  Actions  in  the  Widget  Framework 

Although  actions,  strictly  speaking,  are  not  methods,  writing  them  is  part  of  the  process  of 
writing  a  simple  widget  Fortunately,  you  have  already  seen  action  routines  added  from  the 
application.  Action  routines  look  and  work  the  same  in  the  widget  framework  as  in  the  appli 
cation,  except  that  they  use  instance  structure  fields  as  data  instead  of  the  application  data 
structure  fields.  Example  6-10  shows  the  actions  of  BitmapEdit. 

Example  6-10.  BitmapEdit:  action  routines 

§  static  void 
DrawCell (w,  event) 
§  BitmapEditWidget  w; 
XButtonEvent  *event; 

DrawPixmaps (w->bitmapEdit .draw_gc,  DRAW,  w,  event); 

static  void 
UndrawCell (w,  event) 
BitmapEditWidget  w; 
XButtonEvent  *event; 

DrawPixmaps (w->bitmapEdit .undraw_gc,  UNDRAW,  w,  event); 

static  void 
ToggleCell (w,  event) 
BitmapEditWidget  w; 
XButtonEvent  *event; 

static  int  oldx  =  -1,  oldy  =  -1; 

GC  gc ; 

int  mode; 

int  newx,  newy; 

if  (event->type  !=  ButtonPress) 

tXtWarning ("BitmapEdit:  ToggleCell  action  invoked\ 
by  wrong  event  type."); 

newx  =  (w->bitmapEdit .cur_x  +  event->x)  / 

w->bitmapEdit . cell_size; 
newy  =  (w->bitmapEdit .cur_y  +  event->y)  / 

w->bitmapEdit ,cell_size; 

if  ((mode  -  w->bitmapEdit .cell [newx  +  newy  *  w-> 

bitmapEdit.pixmap_width_in_cells] )  ==  DRAWN)  { 
gc  =  w->bitmapEdit .undraw_gc; 
mode  =  UNDRAW; 

else  { 

gc  =  w->bitmapEdit .draw_gc; 
mode  =  DRAW; 

if  (oldx  !=  newx  | |  oldy  !=  newy)  { 
oldx  =  newx; 
oldy  =  newy; 
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Example  6-10.  BitmapEdit:  action  routines  (continued) 

DrawPixmaps (gc,  mode,  w,  event); 


static  void 

DrawPixmaps (gc,  mode,  w,  event) 

GC  gc  ; 

int  mode; 

BitmapEditWidget  w; 

XButtonEvent  *event; 

int  newx  =  (w->bitmapEdit  .cur_x  +  event->x)  / 

w->bitmapEdit .cell_size; 
int  newy  =  (w->bitmapEdit .cur_y  +  event->y)  / 

w->bitmapEdit .cell_size; 

XExposeEvent  fake  event; 

— 

/*  if  already  done,  return  */ 
if  (w->bitmapEdit .cell [newx  +  newy  * 

w->bitmapEdit .pixmap_width_in_cells]  ==  mode) 
return; 

/*  otherwise,  draw  or  undraw  */ 

XFillRectangle (XtDisplay (w) ,  w->bitmapEdit .big_picture,  gc, 
w->bitmapEdit .cell_size*newx  +  2, 
w->bitmapEdit .cell_size*newy  +  2, 
(unsigned  int) w->bitmapEdit . cell_size  -  3, 
(unsigned  int) w->bitmapEdit .cell_size  -  3) ; 

w->bitmapEdit .cell [newx  +  newy  * 

w->bitmapEdit .pixmap_width_in_cells]  =  mode; 
info. mode  =  mode; 
info. newx  =  newx; 
info. newy  =  newy; 

fake_event.x  =  w->bitmapEdit .cell_size  *  newx 

-  w->bitmapEdit . cur_x; 
fake_event.y  =  w->bitmapEdit . cell_size  *  newy 

-  w->bitmapEdit . cur_y; 

fake_event .width  =  w->bitmapEdit .cell_size; 
fake_event .height  =  w->bitmapEdit .cell_size; 

Redisplay (w,  &fake_event) ; 
XtCallCallbacks(w,  XtNcallback,  sinfo) ; 

Notice  that  as  in  methods,  the  widget  instance  pointer  passed  in  is  cast  to  the  desired  type  by 
declaring  the  argument  as  type  BitmapEditWidget.  In  other  widgets  you  will  also  see 
the  argument  declared  as  type  widget,  and  then,  in  the  first  line  of  the  action,  cast  to  the 
desired  type. 
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An  action  routine  in  widget  code  can  set  and  read  fields  in  the  widget  instance  structure 
passed  in,  while  an  action  added  from  the  application  can  access  its  own  application  data 
structure  but  not  the  widget's  internal  data  structure  because  of  the  encapsulation  rule  (see 
Section  2.1.6.3).  This  is  one  of  the  advantages  of  moving  this  code  into  a  widget. 

You  should  now  be  ready  to  go  back  to  the  end  of  Chapter  5,  Inside  a  Widget,  and  follow  the 
directions  to  write  your  first  widget  You  will  need  to  review  parts  of  both  Chapter  5  and  this 
chapter  as  the  process  of  actually  writing  a  widget  raises  new  questions. 
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7 


Events,  Translations,  and  Accelerators 


This  chapter  describes  the  complete  syntax  of  translation  tables,  and 
describes  a  mechanism  called  accelerators  for  mapping  events  in  one  widget 
to  actions  in  another. 
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7 

Events,  Translations, 
and  Accelerators 


Events  drive  the  application.  They  send  a  great  variety  of  information  from  the  server  to  the 
client,  and  from  the  user  to  the  application.  More  knowledge  of  events  is  necessary  both  to 
use  existing  widgets  successfully  in  large  applications  and  to  write  widgets. 

Events  are  sufficiently  central  to  X  that  we've  devoted  two  chapters  in  this  book  to  them. 
This  chapter  provides  a  closer  look  at  translations  and  actions;  Chapter  8  looks  at  lower-level 
event  handlers,  as  well  as  at  other  sources  of  input. 

The  basic  concept  and  use  of  translations  and  actions  has  already  been  described.  But  trans 
lation  tables  have  a  complicated  syntax  which  can  be  used  to  do  much  more  than  the  simple 
mappings  you  have  seen  up  to  now.  Translation  tables  can  detect  user-interface  idioms  such 
as  double-  and  triple-button  clicks  or  key  combinations  such  as  Shift-Meta-M.  This  chapter 
focuses  on  the  more  advanced  features  of  translation  tables. 

Next,  we  discuss  a  variation  of  translations  called  accelerators.  Accelerators,  which  were 
introduced  in  Release  3,  bind  events  that  occur  in  one  widget  to  actions  in  another.  This  is  a 
flexible  feature  with  many  uses.  One  common  use  is  to  supply  a  keyboard  interface  to  a  nor 
mally  pointer-driven  application.  By  adding  accelerators  to  the  top-level  window  of  the 
application,  a  keyboard  event  typed  with  the  pointer  anywhere  in  the  application  can  be 
translated  into  an  action  in  the  correct  widget  The  name  "accelerator"  comes  from  the  fact 
that  many  advanced  users  find  it  faster  to  use  keyboard  shortcuts  instead  of  menus. 

As  mentioned  in  Chapter  3,  More  Widget  Programming  Techniques,  it  is  a  very  good  idea  to 
specify  translation  tables  (and  accelerator  tables,  too)  in  the  application-defaults  file  instead 
of  hardcoding  them  in  the  application,  especially  while  an  application  is  under  development. 
This  lets  you  develop  the  translations  and  accelerators  without  recompiling  the  application 
every  time  you  want  to  make  a  change. 
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7.1   Translation  Table  Syntax 

If  you  are  reading  this  book  in  sequence,  you've  already  seen  translations  used  many  times. 
However,  we  haven't  given  a  formal  description  of  their  syntax  or  a  complete  listing  of  the 
events  you  can  translate. 

A  translation  table  consists  of  an  optional  directive,  which  specifies  how  the  table  should  be 
merged  with  any  other  existing  translation  tables,  followed  by  a  series  of  production  rules,  of 
the  form: 

[ modifier _list]  <event>  [ ,  <event> ...  ]  [  (count)  ]  [detail]  :    action (  [arguments]  )  [    action...  ] 

where  brackets  ([  ])  indicate  optional  elements,  an  ellipsis  (...)  indicates  repetition,  and 
italics  indicate  substitution  of  an  actual  modifier,  event,  detail,  or  action  name. 

At  a  minimum,  a  translation  must  specify  at  least  one  event,  specified  by  a  predefined  event 
name  or  abbreviation  enclosed  in  angle  brackets;  a  colon  separator;  and  at  least  one  action. 
However,  a  sequence  of  events  can  be  specified;  likewise,  more  than  one  action  can  be 
invoked  as  a  result.  The  scope  of  event  matching  can  be  limited  by  one  or  more  optional 
modifiers,  and  in  the  case  of  some  events,  by  a  "detail"  field  that  specifies  additional  informa 
tion  about  the  event  (For  example,  for  key  events,  the  detail  field  specifies  which  key  has 
been  pressed.)  Repeated  occurrences  of  the  same  event  (e.g.,  a  double-click)  can  be  specified 
by  a  count  value  in  parentheses.  A  colon  and  optional  white  space  separates  the  translation 
and  the  action. 

The  examples  below  are  all  valid  translations: 

<Enter>:       doit()  invoke  doit()  on  an  EnterWindow  event 

<BtnlDown>,  <BtnlUp>:       doit()  invoke  doit()  on  a  click  of  Button  1 

<BtnlUp>(2):       doit()  invoke  doit()  on  a  double-click  of  Button  1 

Buttonl<Btn2Down>, <Btn2Up> :       doit ( ) 

invoke  doit()  on  a  click  of  Button  2 
while  Button  1  is  held  down 
Shi  f  t  <BtnDown>  :       doit  ( )  invoke  doit()  on  a  click  of  any  button  while 

the  shift  key  is  held  down 
<Key>y :      doit  ( )  invoke  doit()  when  the  y  key  is  pressed 

A  translation  table  is  a  single  string,  even  when  composed  of  multiple  translations.  If  a  trans 
lation  table  consists  of  more  than  one  translation,  the  actual  newlines  are  escaped  with  a 
backslash  (except  for  the  last  one),  and  character  newlines  are  inserted  with  the  \n  escape 
sequence,  as  you've  seen  demonstrated  in  examples  throughout  this  book. 

The  following  sections  provide  additional  detail  on  each  of  the  elements  of  an  event  transla 
tion.  We'll  talk  first  about  the  directive,  followed  by  event  specifiers,  details,  modifiers,  and 
counts.  We'll  also  provide  some  pointers  on  the  proper  sequence  of  translations,  and  discuss 
what  happens  when  translations  overlap. 
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7.1.1  The  Directive 

As  we've  already  seen,  the  three  possible  directives  are  treplace,  #override,  or 
^augment. 

# replace  says  to  completely  replace  the  value  of  the  translations  resource  in  the 
widget  If  no  directive  is  specified,  #  replace  is  the  default. 

The  difference  between  ^override  and  #augment  is  more  subtle.  They  differ  in  how 
they  treat  event  combinations  in  the  new  translation  that  also  appear  in  the  old.  With 
#override,  the  new  translation  takes  priority,  while  with  #augment,  the  old  one  does. 

For  example,  say  a  widget  has  a  default  translation  table  that  includes  a  translation  for  the 
Return  key,  and  an  application  that  uses  this  widget  has  an  application-defaults  file  consisting 
of  a  translation  table  that  applies  to  this  widget  If  the  translation  table  in  the  application- 
defaults  file  began  with  #override,  any  translation  for  the  Return  key  would  take  priority 
over  the  default  translation  for  the  Return  key.  On  the  other  hand,  if  the  translation  table  in 
the  application-defaults  file  began  with  #augment,  the  default  translations  would  take  pri 
ority. 

Remember  that  the  difference  between  ^augment  and  #override  is  only  in  the  treat 
ment  of  overlapping  translations.  Any  translations  added  with  either  directive  for  events  that 
do  not  akeady  appear  in  the  existing  translation  table  will  always  be  added. 

Because  of  potential  overlap  between  translations,  when  you  are  debugging  your  intended 
translations  it  is  best  to  use  #replace  at  first,  then  test  with  #augment  or  ^override 
as  appropriate  once  you  are  sure  that  the  translations  themselves  have  the  desired  effect. 

7.1.2  Selecting  the  Events  to  Translate 

An  X  event  is  a  packet  of  data  sent  by  the  server  to  a  client  in  response  to  user  behavior  or  to 
window  system  changes  resulting  from  interactions  between  windows.  There  are  33  different 
types  of  events  defined  by  X.  Most  (though  not  all*)  events  can  be  thought  of  as  occurring  in 
a  window:  the  pointer  entering  or  leaving  a  window,  pointer  motion  within  a  window, 
pointer  button  presses,  key  presses,  and  so  on.  However,  most  events  are  not  sent  to  a  win 
dow  unless  the  window  has  explicitly  selected  that  event  type;  events  are  selected  on  a  per- 
window  basis.  In  Xlib  programming,  events  are  selected  by  specifying  an  event  mask  as  a 
window  attribute.  Some  events,  which  are  sent  to  all  windows  regardless  of  whether  a  win 
dow  has  selected  them  or  not  are  called  non-maskable  events.  One  of  the  most  complex 
aspects  of  Xlib  programming  is  designing  the  event  loop,  which  must  take  into  account  all  of 
the  possible  events  that  can  occur  in  a  window. 

Xt's  translation  manager  selects  the  events  that  are  specified  in  the  current  translation  table 
for  each  widget  In  translations,  events  can  be  specified  either  by  their  actual  names,  as 
shown  in  column  1  of  Table  7-1,  or  by  means  of  the  abbreviations  shown  in  column  2.  A 


"Others  reflect  internal  changes  in  the  window  system  not  related  to  any  window.  For  example,  a  KeymapNot  i  f  y 
event  occurs  in  response  to  a  change  in  the  mappings  of  keysyms  (portable  key  symbols)  to  keycodes  (actual  codes 
generated  by  physical  keys). 
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complete  reference  to  each  event  type  is  provided  in  Appendix  C,  Event  Reference,  in  Vol 
ume  Five,  X  Toolkit  Intrinsic*  Reference  Manual. 

Table  7-1.  Event  Type  Abbreviations  in  Translation  Tables 


Event  Type 

Abbreviations 

Description 

ButtonPress 

BtnDown 

Any  pointer  button  pressed 

BtnlDown 

Pointer  button  1  pressed 

Btn2Down 

Pointer  button  2  pressed 

BtnSDown 

Pointer  button  3  pressed 

Btn4Down 

Pointer  button  4  pressed 

BtnSDown 

Pointer  button  5  pressed 

But  tonRe  lease 

BtnUp 

Any  pointer  button  released 

BtnlUp 

Pointer  button  1  released 

Btn2Up 

Pointer  button  2  released 

Btn3Up 

Pointer  button  3  released 

Btn4Up 

Pointer  button  4  released 

Btn5Up 

Pointer  button  5  released 

KeyPress 

Key 

Key  pressed 

KeyDown 

Key  pressed 

Ctrl 

KeyPress  with  Ctrl  modifier 

Meta 

KeyPress  with  Meta  modifier 

Shift 

KeyPress  with  Shift  modifier 

KeyRelease 

KeyUp 

Key  released 

MotionNotify 

Motion 

Pointer  moved 

PtrMoved 

Pointer  moved 

MouseMoved 

Pointer  moved 

BtnMotion 

Pointer  moved  with  any  button  held  down 

BtnlMotion 

Pointer  moved  with  button  1  held  down 

Btn2Motion 

Pointer  moved  with  button  2  held  down 

BtnSMotion 

Pointer  moved  with  button  3  held  down 

Btn4Motion 

Pointer  moved  with  button  4  held  down 

BtnSMotion 

Pointer  moved  with  button  5  held  down 

EnterNotify 

Enter 

Pointer  entered  window 

EnterWindow 

Pointer  entered  window 

LeaveNotify 

Leave 

Pointer  left  window 

LeaveWindow 

Pointer  left  window 

Focusln 

Focusln 

This  window  is  now  keyboard  focus 

FocusOut 

FocusOut 

This  window  lost  keyboard  focus 

KeymapNot  i  f  y 

Keymap 

Keyboard  mappings  changed 

Expose 

Expose 

Part  of  window  needs  redrawing 

GraphicsExpose 

GrExp 

Source  of  copy  unavailable 

NoExpose 

NoExp 

Source  of  copy  available 

ColormapNotify 

Clrmap 

Window's  colormap  changed 

PropertyNotify 

Prop 

Property  value  changed 

VisibilityNotify 

Visible 

Window  has  been  obscured 

ResizeRequest 

ResReq 

Redirect  resize  request  to  window  manager 
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Table  7-1.  Event  Type  Abbreviations  in  Translation  Tables  (continued) 


Event  Type 

Abbreviations 

Description 

CirculateNotify 

Circ 

Stacking  order  modified 

Conf  igureNotify 

Configure 

Window  resized  or  moved 

DestroyNotify 

Destroy 

Window  destroyed 

GravityNotify 

Grav 

Window  moved  due  to  win  gravity  attribute 

MapNotify 

Map 

Window  mapped 

Great  eNot  if  y 

Create 

Window  created 

ReparentNotify 

Reparent 

Window  reparented 

UnmapNotify 

Unmap 

Window  unmapped 

CirculateRequest 

CircRec 

Redirect  stacking  order  change  to  window  manager 

ConfigureRequest 

ConfigureReq 

Redirect  move  or  resize  request  to  window  manager 

MapRequest 

MapReq 

Redirect  window  map  request  to  window  manager 

MappingNotify 

Mapping 

Keyboard  mapping  changed 

ClientMessage 

Message 

Client-dependent 

Select  ionClear 

SelClr 

Current  owner  is  losing  selection 

SelectionNotify 

Select 

Selection  is  ready  for  requestor 

Select  ionRequest 

SelReq 

Request  for  selection  to  current  owner 

Many  of  these  events  are  handled  automatically  by  the  Toolkit  separately  from  the  translation 
mechanism.  For  example,  Expose  events  are  automatically  sent  to  the  expose  method  of 
the  appropriate  widget*  When  there  is  also  a  translation  for  Expose  events,  the  action  is 
called  in  addition  to  the  expose  method.  The  only  reason  you  would  need  a  translation  for 
Expose  events  is  to  add  drawing  to  a  Core  widget  Since  the  Core  widget  doesn't  have  an 
expose  method,  there  is  rarely  if  ever  a  case  where  there  is  both  an  expose  method  and  a 
translation  for  Expose  events  for  the  same  widget  The  point  to  remember  is  that  any  event 
can  be  specified  in  a  translation,  even  when  that  event  is  also  used  in  some  other  way  by  Xt. 

Several  of  the  *Notif  y  events  are  automatically  handled  by  the  Toolkit  Xt  places  this 
information  in  internal  structures  so  that  it  can  satisfy  queries  for  widget  positions  and 
geometries  without  querying  the  server.  MappingNotify  events  are  automatically  han 
dled;  Xt  gets  the  current  keyboard  mapping  from  the  server.  visibilityNotif  y  events 
are  handled  automatically  if  the  visible_interest  field  in  the  Core  structure  is  set  to 
TRUE  (see  Section  8.4.1). 

With  the  exception  of  Select  ionRequest,  the  *Request  events  are  intended  for  use 
only  by  window  managers.  The  selection  events  are  described  in  Chapter  10,  Inter-Client 
Communications . 


'GraphicsExpose  and  NoExpose  events  are  not  handled  automatically  by  XL  If  you  are  writing  a  widget,  you 
must  explicitly  select  GraphicsExpose  and  NoExpose  events  by  setting  the  graphics_exposures  GC 
component  in  a  GC.  These  events  are  useful  when  your  application  copies  from  a  visible  window  with  XCopyArea 
or  XCopyP  1  ane.  They  notify  the  application  when  part  of  the  source  of  the  copy  is  obscured.  (While  xbitmap  and 
BitmapEdit  use  XCopyArea  and  XCopyP  lane,  they  copy  from  an  off-screen  pixmap  that  cannot  be  obscured, 
and  therefore  GraphicsExpose  and  NoExpose  events  are  not  needed.  For  a  description  of  these  events,  see 
Chapter  5,  The  Graphics  Context,  in  Volume  One,  Xlib  Programming  Manual.) 


Events,  Translations,  and  Accelerators 


193 


Whether  or  not  they  are  already  handled  by  Xt  or  in  translations,  events  can  also  be  selected 
explicitly  by  installing  event  handlers  in  a  widget  (as  described  in  Chapter  8,  More  Input 
Techniques). 

7.1.3    Details  in  Keyboard  Events 

As  you've  seen,  Xt  provides  special  event  abbreviations  to  specify  which  pointer  button  was 
pressed  or  released.  With  key  events,  this  approach  would  be  a  little  impractical,  since  there 
are  so  many  keys.  Instead,  the  Translation  Manager  allows  you  to  follow  the  event  specifica 
tion  with  an  optional  detail  field.  That  is: 

<Key>:       doit() 

means  that  you  want  the  doit  ()  action  to  be  invoked  when  any  key  has  been  pressed, 
while: 

<Key>y:       doit() 

means  that  you  want  the  doit  ( )  action  to  be  invoked  only  if  the  y  key  has  been  pressed. 

What  you  actually  specify  as  the  detail  field  of  a  Key  event  is  a  keysym,  as  defined  in  the 
header  file  <Xlllkeysymdef.h>*  Keysyms  begin  with  an  XK_  prefix,  which  is  omitted  when 
they  are  used  in  translations. 

Before  we  explain  any  further,  we  need  to  review  X's  keyboard  model,  which,  like  many 
things  in  X,  is  complicated  by  the  design  goal  of  allowing  applications  to  run  equally  well  on 
machines  with  very  different  hardware. 

The  keyboard  generates  KeyPress  events,  and  may  or  may  not  also  generate  Key- 
Release  events.  These  events  contain  a  server-dependent  code  that  describes  the  key 
pressed,  called  a  keycode.  Modifier  keys,  such  as  Shift  and  Control,  generate  events  just  like 
every  other  key.  In  addition,  all  key  events  also  contain  information  about  which  modifier 
keys  and  pointer  buttons  were  held  down  at  the  time  the  event  occurred. 

Xt  provides  a  routine  that  translates  keycode  and  modifier  key  information  from  an  event  into 
a  portable  symbolic  constant  called  a  keysym.  A  keysym  represents  the  meaning  of  the  key 
pressed,  which  is  usually  the  symbol  that  appears  on  the  cap  of  the  key.  For  example,  when 
the  a  key  is  pressed,  the  keysym  is  XK_a;  when  the  same  key  is  pressed  while  the  Shift  key  is 
held  down,  the  resulting  keysym  is  XK_A  (upper  case).  Note  that  even  though  both  the  a  and 
the  A  events  have  the  same  keycode,  they  generate  a  different  keysym  because  they  occurred 
with  different  modifier  keys  engaged.  (The  mapping  between  keycodes  and  keysyms  is  dis 
cussed  further  in  Section  13.4.) 

You  may  specify  either  the  keysym  name,  omitting  the  XK_  prefix,  or  its  hexadecimal  value 
(also  shown  in  <Xlllkeysymdef.h>),  prefixed  by  Ox  or  Ox  (zero  followed  by  x  orX). 


*Note,  however,  that  this  file  includes  foreign  language  keysym  sets  that  are  not  always  available.  Only  the  MIS 
CELLANY,  LATTN1  through  LATTN4,  and  GREEK  sets  are  always  available. 
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This  is  fairly  straightforward,  though  there  are  several  provisos: 

•  The  keysym  for  nonalphanumeric  keyboard  keys  may  not  always  be  obvious;  you  will 
need  to  look  in  <Xlllkeysymdef.h>.   For  example,  the  keyboard  for  the  Sun  workstation 
has    keys    labeled    "Left"    and    "Right"     Their    keysyms    are    XK_Meta_L    and 
XK_Meta_R,  respectively.   Fortunately,  most  common  named  keys  have  mnemonic 
keysym     names     (XK_Return,     XK_Linefeed,     XK_BackSpace,     XK_Tab, 
XK_Delete,  and  so  on)  so  you  can  often  get  by  without  looking  them  up.  Notice, 
though,  the  small  things  that  can  trip  you  up:  Backspace,  not  Backspace,  but  Linefeed, 
not  LineFeed.  You  can't  count  on  consistency. 

•  The  definitions  in  <Xlllkeysymdef.h>  spell  out  keysym  names  for  punctuation  and  other 
special  characters.  For  example,  you'll  see  XK_question  rather  than  XK_?,  and  so 
on.  Nonetheless,  you  need  not  use  this  long  keysym  name;  the  Translation  Manager  will 
accept  the  equivalent  single  character,  as  long  as  it  is  a  printing  character.  This  is  also 
true  of  digits.  There  are  a  few  exceptions,  namely  the  characters  that  have  special  mean 
ing  in  a  translation  table.  If  you  ever  need  a  translation  for  colon,  comma,  angle  brackets, 
or  backslash,  you'll  have  to  use  the  keysym  name  rather  than  the  single  printing  charac 
ter. 

•  The  keycode-to-keysym  translator  built  into  the  Translation  Manager  makes  case  distinc 
tions  only  if  the  key  event  is  prefaced  with  the  colon  (:)  modifier.   This  means  that 
<Key>a  and  <Key>A  will  be  treated  identically  by  default.  We'll  return  to  this  subject 
when  we  discuss  modifiers. 

In  sum,  the  following  are  all  valid  key  event  translations: 

<Key>q :       quit  ( )  invoke  quit()  when  q  or  Q  is  pressed 

:  <Key  >  ?  :      he  lp  ( )  invoke  help()  when  1  (but  not  / )  is  pressed 

<Key>Return :      newline  ( )  invoke  newline()  when  the  Return  key  is  pressed 

<Key>:      insert_char  ()  invoke  insert_char()  when  any  key  is  pressed 


7.1.4   Details  in  Other  Event  Types 

Key  events  are  the  most  likely  to  require  details,  but  they  are  also  available  for  several  other 
event  types. 

Trivially,  the  detail  values  Buttonl  through  Buttons  can  be  supplied  as  details  for 
ButtonPress  or  But tonRe lease  events;  because  of  the  available  abbreviations, 
though,  these  should  not  often  be  necessary.  It  is  easier  to  say: 

<BtnlDown>:  quit() 

than: 

<BtnDown>Buttonl :       quit() 

The  EnterNotify,  LeaveNotify,  Focus  In,  and  FocusOut  events  can  take  as 
details  any  of  the  notify  mode  values  shown  in  Table  7-2. 
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Table  7-2.  Notify  Mode  Values  for  Enter,  Leave,  and  Focus  Events 


Detail 


Description 


Normal 

Grab 

Ungrab 


Event  occurred  as  a  result  of  a  normal  window  crossing 
Event  occurred  as  a  result  of  a  grab 
Event  occurred  when  a  grab  was  released 


Normally,  EnterNotify  and  LeaveNotify  events  are  generated  when  the  pointer 
enters  or  leaves  a  window.  Focus  In  and  FocusOut  events  are  generated  when  a  window 
gains  or  loses  the  keyboard  focus.  When  this  occurs  depends  on  the  style  of  window  man 
ager  being  used.  With  a  "real-estate-driven"  window  manager  like  uwm,  the  keyboard  focus 
automatically  follows  the  pointer,  so  Focus  In  and  FocusOut  events  will  occur  at  the 
same  time  as  EnterNotify  and  LeaveNotify  events.  Other  window  managers,  such 
as  the  Motif  window  manager,  mwm,  support  a  "click-to-type"  style  of  interaction  similar  to 
that  used  by  the  Macintosh.  The  user  clicks  in  a  window  to  give  it  the  keyboard  focus. 
Thereafter,  keyboard  events  are  sent  to  that  window  regardless  of  the  pointer  position.  A 
grab,  which  is  usually  implemented  by  a  pop-up  window  or  a  window  manager,  has  a  similar 
effect,  causing  keyboard  and/or  pointer  input  to  be  constrained  to  a  particular  window. 

The  detail  values  for  these  event  types  correspond  to  the  mode  member  of  the  appropriate 
event  structures.  See  Appendix  C,  Event  Reference,  in  Volume  Five,  X  Toolkit  Intrinsics  Ref 
erence  Manual,  for  more  details. 

Details  for  additional  events  are  being  added  in  Release  4. 


7.1.5    Modifiers 


Certain  events  include  as  part  of  their  data  the  state  of  the  pointer  buttons  and  special  key 
board  modifier  keys  at  the  time  the  event  was  generated.  The  events  for  which  this  state  is 
available  include  ButtonPress,  ButtonRelease,  MotionNotify,  KeyPress, 
KeyRelease,  EnterNotify,  and  LeaveNotify. 

For  these  events,  you  can  specify  a  desired  modifier  state  using  one  or  more  of  the  modifier 
keywords  listed  in  Table  7-3.  An  error  is  generated  if  you  specify  modifiers  with  any  other 
types  of  events. 

Table  7-3.  Modifiers  Used  in  Translation  Tables 


Modifier 

Abbreviation* 

Description 

Ctrl 

c 

Control  key  is  held  down 

Shift 

s 

Shift  key  is  held  down 

Lock 

1 

Caps  Lock  is  in  effect 

Meta 

m 

Meta  key  is  held  down 

Hyper 

h 

Hyper  key  is  held  down 

Super 

su 

Super  key  is  held  down 
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Table  7-3.  Modifiers  Used  in  Translation  Tables  (continued) 


Modifier 


Abbreviation* 


Description 


Alt 

Modi 

Mod2 

Mod3 

Mod4 

Mod5 

Buttonl 

Button2 

Buttons 

Button4 

Button5 


Alt  key  is  held  down 
Modi  key  is  held  down 
Mod2  key  is  held  down 
Mod3  key  is  held  down 
Mod4  key  is  held  down 
Mod5  key  is  held  down 
Pointer  Button  1  is  held  down 
Pointer  Button  2  is  held  down 
Pointer  Button  3  is  held  down 
Pointer  Button  4  is  held  down 
Pointer  Button  5  is  held  down 


7.1 .5.1    Physical  Keys  Used  as  Modifiers 

The  meaning  of  the  Meta,  Hyper,  Super,  Alt,  and  Modi  through  Mod5  keywords  may 
differ  from  server  to  server.  Not  every  keyboard  has  keys  by  these  names,  and  even  if 
keysyms  are  defined  for  them  in  <Xlllkeysymdef.h>,  they  may  not  be  available  on  the  physi 
cal  keyboard.! 

For  example,  the  file  <Xlllkeysymdef.h>  includes  the  following  definitions: 

/*   Modifiers    */ 


#define  XK_Shift_L 
tdef ine  XK_Shift_R 
#define  XK_Control_L 
#define  XK_Control_R 
fdefine  XK_Caps_Lock 
#define  XK  Shift  Lock 


#def ine 
#define 
#def ine 
#define 
tdef ine 
tdef ine 
#define 
#def ine 


XK_Meta_L 

XK_Meta_R 

XK_Alt_L 

XK_Alt_R 

XK_Super_L 

XK_Super_R 

XK_Hyper_L 

XK_Hyper_R 


OxFFEl  /*  Left  shift  */ 

OxFFE2  /*  Right  shift  */ 

OxFFE3  /*  Left  control  */ 

OxFFE4  /*  Right  control  */ 

OxFFES  /*  Caps  lock  */ 

OxFFE6  /*  Shift  lock  */ 

OxFFE7  /*  Left  meta  */ 

OxFFES  /*  Right  meta  */ 

OxFFE9  /*  Left  alt  */ 

OxFFEA  /*  Right  alt  */ 

OxFFEB  /*  Left  super  */ 

OxFFEC  /*  Right  super  */ 

OxFFED  /*  Left  hyper  */ 

OxFFEE  /*  Right  hyper  */ 


"Though  these  abbreviations  are  defined  in  the  Translation  Manager  specification,  and  may  be  implemented  by  some 
vendors,  they  don't  work  in  MIT's  sample  implementation,  and  thus  probably  aren't  present  in  others  as  well.  This 
may  change  in  Release  4. 

fThe  contents  of  <Xll/keysymdef.h>  are  the  same  on  every  machine.  What  is  different  is  the  default  mapping  of 
keysyms  to  physical  keycodes,  which  occurs  in  the  server  source.  The  only  way  to  find  out  the  mappings  is  through 
documentation  (which  is  usually  not  available)  or  experimentation  (as  described  in  Chapter  1 1  of  Volume  Three,  X 
Window  System  User's  Guide,  Second  Edition). 
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There  are  two  things  you  must  learn  before  you  can  use  these  modifiers: 

1.  Which  physical  key  generates  a  given  keysym,  if  it  is  not  obvious  from  the  name. 

2.  Which  modifiers  are  valid  on  your  server. 

The  best  way  to  find  out  what  keysym  a  key  generates  is  with  the  xev  client,  which  prints 
detailed  information  about  every  event  happening  in  its  window.  To  find  out  a  keysym,  run 
xev,  move  the  pointer  into  its  window,  and  then  press  the  key  in  question. 

On  the  Sun-3,  there  is  only  one  control  key,  on  the  left  side  of  the  keyboard.  It  generates  the 
keysym  XK_Control_L.  There  are  two  shift  keys,  one  on  each  side,  which  generate  the 
keysyms  XK_Shift_L  and  XK_Shift_R.  The  Meta  modifier  is  mapped  to  the  keys 
labeled  "Left"  and  "Right"  Even  though  there  is  an  Alternate  keyboard  key,  which  gener 
ates  the  keysym  XK_Alt_R,  this  key  is  not  recognized  as  a  modifier.  There  are  no  Super 
and  Hyper  keys. 

The  list  of  valid  modifiers  can  be  displayed  with  the  xmodmap  client,  as  follows: 

isla%  xmodmap 

xmodmap:   up  to  2  keys  per  modifier,  (keycodes  in  parentheses) : 

shift        Shift_L  (Ox6a) ,   Shift_R  (0x75) 

lock         Caps_Lock  (Ox7e) 

control      Control_L  (0x53) 

modi        Meta_L  (Ox7f ) ,   Meta_R  (0x81) 

mod2 

mod3 

mod4 

mod5 

That  is,  either  of  the  two  shift  keys  will  be  recognized  as  the  Shift  modifier,  the  Caps  Lock 
key  as  the  Lock  modifier,  and  either  the  Left  or  Right  keys  as  the  Meta  modifier.  The  Left 
and  Right  keys  are  also  mapped  to  the  Modi  modifier.  The  Alt  key  is  not  recognized  as  a 
modifier. 

xmodmap  also  allows  you  to  add  keysyms  to  be  recognized  as  the  given  modifier.  For 
example,  the  following  command  would  cause  the  Fl  function  key  to  be  recognized  as  mod2: 

isla%  xmodmap  -•   'add  xnod2   «  Fl' 

For  more  information  on  xmodmap  and  xev,  see  Chapter  1 1  of  Volume  Three,  X  Window  Sys 
tem  User's  Guide  (Second  Edition). 

7.1 .5.2    Default  Interpretation  of  the  Modifier  List 

If  no  modifiers  are  specified  in  a  translation,  the  state  of  the  modifier  keys  and  pointer  buttons 
makes  no  difference  to  a  translation.  For  example,  the  translation: 

<Key>q:         quit() 

will  cause  the  quit  action  to  be  invoked  when  the  q  key  is  pressed,  regardless  of  whether 
the  Shift,  Ctrl,  Meta,  or  Lock  key  is  also  held,  and  regardless  of  the  state  of  the  pointer  but 
tons. 
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Likewise,  if  a  modifier  is  specified,  there  is  nothing  to  prohibit  other  modifiers  from  being 
present  as  well.  For  example,  the  translation: 

Shift <Key>q :    quit { ) 

will  take  effect  even  if  the  Ctrl  key  is  held  down  at  the  same  time  as  the  Shift  key  (and  the  q 
key). 

There  are  a  number  of  special  modifier  symbols  that  can  be  used  to  change  this  forgiving 
state  of  affairs.  These  symbols  are  shown  in  Table  7-4. 

Table  7-4.  Modifier  Symbols 


Symbol 


None 


Description 


No  modifiers  may  be  present 

No  modifiers  except  those  explicitly  specified  may  be  present 

Apply  shift  modifier  to  key  event  before  comparing 

The  modifier  immediately  following  cannot  be  present 


The  syntax  of  these  special  modifiers  symbols  is  somewhat  inconsistent,  and  made  clearest 
by  example. 

M.5.3    Prohibiting  a  Modifier 

The  tilde  (~)  is  used  to  negate  a  modifier.  It  says  that  the  specified  modifier  may  not  be 
present  For  example, 

Buttonl<Key>:   doit{) 

says  that  doit  ()  should  be  invoked  by  a  press  of  any  key  when  button  1  is  being  held 
down,  while 

~Buttonl<Key>:      doit{) 

says  that  doit  ( )  should  be  invoked  by  a  press  of  any  key  except  when  button  1  is  being 
held  down. 

A  ~  applies  only  to  the  modifier  that  immediately  follows  it  For  example, 
"Shift   Ctrl<Key>:      doit() 

says  that  doit  ( )  should  be  invoked  when  Ctrl  is  held  down  in  conjunction  with  any  key, 
except  if  Shift  is  depressed  at  the  same  time. 
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7.1.5.4  Requiring  an  Exact  Match 

An  exclamation  point  at  the  start  of  a  modifier  list  states  that  only  themo  difiers  in  that  list 
may  be  present,  and  must  match  the  list  exactly.  For  example,  if  the  translation  is  specified 
as: 

!Shift<Key>q:   quit() 

the  translation  will  take  effect  only  if  the  Shift  key  is  the  only  modifier  present;  if  Caps  Lock 
were  in  effect,  or  if  a  pointer  button  were  depressed  at  the  same  time,  the  translation  would 
no  longer  work. 

The  modifier  None  is  the  same  as  !  with  no  modifiers  specified.  That  is: 

None<Key>q :       quit ( ) 
or 

!<Key>q:       quit() 

will  invoke  quit  only  if  no  modifier  keys  at  all  are  pressed. 

7.1 .5.5  Paying  Attention  to  the  Case  of  Keysyms 

The  :  modifier,  like  !,  goes  at  the  beginning  of  the  modifier  list  and  affects  the  entire  list.  This 
one  is  really  in  a  category  by  itself,  since  it  applies  only  to  Key  events. 

Normally,  the  translations: 

<Key>a:      doit() 
and 

<Key>A:       doit() 

have  identical  results:  both  will  match  either  a  lower-case  or  an  upper-case  A.  Preceding 
the  translation  with  a  colon  makes  the  case  of  the  keysym  significant.  For  example,  to  create 
commands  like  those  in  the  UNIX  vi  editor,  you  might  specify  the  following  translations: 

:<Key>a:   append ()   \n\ 
:<Key>A:   appendToEndOfLine () 

In  this  case,  a  and  A  are  distinct.  You  could  achieve  somewhat  the  same  result  by  specifying: 

"Shift <Key>a:   append ()   \n\ 
Shift<Key>a:   appendToEndOfLine () 

However,  this  second  example  is  both  more  complex  and  less  effective.  While  the  colon  syn 
tax  will  match  an  upper-case  character  generated  as  a  result  of  either  the  Shift  or  Lock  modi 
fiers,  the  example  shown  immediately  above  will  handle  only  Shift.  You  could  use  the  fol 
lowing  translation  to  prohibit  both  Shift  and  Lock  from  being  asserted,  but  there  is  no  way  to 
specify  that  either  Shift  or  Lock  may  be  present 

~ Shift    ~Lock<Key>a:      append ()       \n\ 
Shift<Key>a:      appendToEndOfLine () 

Note  that  you  cannot  specify  both  the  Shift  or  Lock  modifier  and  an  upper-case  keysym.  For 
example: 
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Shift <Key>A:      doit() 
will  have  no  effect,  since  you  cannot  further  shift  an  uppercase  character. 

For  more  details  on  how  the  Toolkit  handles  the  ins  and  outs  of  case  conversion,  see  Chapter 
13,  Miscellaneous  Toolkit  Programming  Techniques.  A  more  rigorous  discussion  of  how  the 
colon  modifier  works  is  also  given  in  Appendix  F,  Translation  Table  Syntax,  in  Volume  Five, 
X  Toolkit  Intrinsics  Reference  Manual. 

7.1.6   Event  Sequences 

The  left-hand  side  of  a  translation  may  specify  a  single  event  or  a  sequence  of  events  that 
must  occur  for  the  action  to  be  invoked.  For  example,  we  might  want  a  certain  action  to  be 
invoked  only  if  the  first  button  is  clicked  twice  in  succession. 

Each  event  specified  in  the  sequence  is  one  of  the  abbreviations  for  an  event  type  enclosed  in 
angle  brackets,  optionally  led  by  any  set  of  modifiers  and  special  characters,  as  described  in 
Section  7.1.5.  Each  modifier-list/event  pair  in  the  sequence  is  separated  by  a  comma. 

For  example,  the  translation  to  perform  an  action  in  response  to  a  button  press  followed  by  a 
release  of  the  same  button  (a  button  click)  is  the  following: 

<BtnDown>,<BtnUp>  :  doit() 

Button  press  events  may  be  specified  in  the  translation  table  followed  by  a  count  in  parenthe 
ses  to  distinguish  a  multiple  click.  Xt  uses  a  timing  technique  to  distinguish  multiple  clicks. 
The  translation  to  detect  a  double  click  is: 

<BtnlDown>(2)  :  doit() 
or 

<BtnlUp>(2)  :  doit() 

Notice  that  though  they  have  the  same  effect  for  the  user,  these  two  translations  are  actually 
interpreted  differently.  The  first  is  equivalent  to  saying: 

<BtnlDown>, <BtnlUp>, <BtnlDown> :   doit { ) 

while  the  second  is  equivalent  to: 

<BtnlDown>, <BtnlUp>, <BtnlDown>, <BtnlUp> :   doit ( ) 

A  plus  (+)  may  appear  immediately  after  the  count  inside  the  parentheses  to  indicate  that  any 
number  of  clicks  greater  than  the  specified  count  should  trigger  the  action. 

The  following  translation  detects  two  or  more  clicks: 

<BtnlDown>(2+)     :    doit() 
The  maximum  count  that  can  be  specified  is  9. 
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7.1.6.1  Special  Considerations  Involving  Motion  Events 

Beware  of  interaction  between  pointer  motion  events  and  double  clicking.  If  no  motion 
events  are  specified  in  a  translation  table,  these  events  are  never  selected,  so  there  is  no  prob 
lem  if  they  occur  between  other  events.  This  allows  a  double  click  to  be  detected  even  if  the 
user  inadvertently  jiggled  the  pointer  in  the  course  of  the  click.  However,  if  motion  events 
are  selected  for  anywhere  in  the  table,  they  may  interfere  with  the  expansion  of  events  speci 
fied  with  the  repeat  notation.  By  definition,  multiple  clicks  are  detected  only  if  there  are  no 
intervening  events.  Motion  events  would  usually  occur  between  the  button  presses  and 
releases. 

Multiple  motion  events  will  match  any  single  motion  event  selected  in  the  translation.  That 
is: 

<Motion>:      doit() 

will  cause  doit  ( )  to  be  invoked  many  times,  once  for  each  motion  event  generated  by  the 
pointer  movement,  unless  the  compressjmotion  event  filter  is  turned  on  in  the  Core 
class  structure.  (This  filter  is  described  in  Section  8.6.2.) 

7.1 .6.2  Modifiers  and  Event  Sequences 

A  modifier  list  at  the  start  of  an  event  sequence  applies  to  all  events  in  the  sequence.  That  is: 

Shift <BtnDown>,<BtnUp>  :  doit() 

is  equivalent  to: 

Shift <BtnDown>, Shift <BtnUp>  :  doit() 

However,  if  modifiers  and  events  are  interspersed,  the  modifier  applies  only  to  the  event 
immediately  following.  As  an  extreme  case  to  demonstrate  this  behavior,  consider  the  fol 
lowing  translation: 

Ctrl<Btn2Down>,  ~Ctrl<Btn2Up>:  doit() 

which  requires  that  the  CTRL  key  be  depressed  when  pointer  button  2  is  pressed,  but  must  not 
be  depressed  when  it  is  released. 

7.1 .6.3  Using  Modifiers  to  Specify  Button  Event  Sequences 

Remember  that  there  are  modifiers  for  specifying  the  state  of  pointer  buttons  as  well  as  modi 
fier  keys.  This  provides  another  way  of  expressing  some  event  sequences.  For  example,  the 
following  translation  would  invoke  the  action  when  the  Fl  key  is  pressed  while  button  1  is 
being  held  down: 

Buttonl<Key>Fl:     doit() 

This  is  equivalent  to: 

<BtnlDown>,<Key>Fl:   doit() 

The  following  translations  could  be  used  to  call  an  action  when  both  the  first  and  second 
pointer  buttons  are  down,  regardless  of  the  order  in  which  they  are  pressed. 
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! Buttonl<Button2> : doC ( )  \n\ 
!Button2<Buttonl>: doC () 


7.1.6.4    Key  Event  Sequences 

The  Translation  Manager  specification  provides  a  special  syntax  for  specifying  a  sequence  of 
Key  events — as  a  string.  That  is: 

"yes":      doit() 
is  theoretically  equivalent  to: 

<Key>y,<Key>e,<Key>s:   doit () 

We  say  "theoretically"  because,  at  least  in  the  R3  sample  implementation  from  MIT,  the 
"yes"  syntax  does  not  work.  It  may  or  may  not  work  in  other  implementations. 

Within  a  sequence  of  key  events  expressed  as  a  string  (on  systems  where  the  "yes"  syntax 
does  work,  if  any),  the  special  character  *  (circumflex)  means  Ctrl  and  $  means  Meta.  These 
two  special  characters,  as  well  as  double  quotes  and  backslashes,  must  be  escaped  with  a 
backslash  if  they  are  to  appear  literally  in  one  of  these  strings. 


7.1.7   Interactions  Between  Translations 

One  of  the  most  difficult  things  to  learn  about  translations  is  how  to  predict  the  interactions 
between  overlapping  translations. 

7.1 .7.1    Order  of  Translations 

The  order  of  translations  in  a  table  is  important,  because  the  table  is  searched  from  the  top 
when  each  event  arrives,  and  the  first  match  is  taken.  Therefore,  more  specific  events  must 
appear  before  more  general  ones.  Otherwise,  the  more  specific  ones  will  never  be  reached. 

For  example,  consider  a  text  entry  widget  that  wants  to  close  itself  and  dispatch  a  callback 
once  the  user  presses  the  Return  key,  indicating  that  entry  is  complete.  The  widget's  transla 
tions  might  be: 

<Key>Return:   gotData ( )    \n\ 
<Key>:        insertCharO 

If  the  translations  were  specified  in  the  reverse  order: 

<Key>:  insertCharO    \n\ 

<Key>Return:       gotData () 

insertCharO  would  be  called  in  response  to  a  press  of  the  Return  key,  and  got 
Data  ( )  would  never  be  called 

Remember  that  the  translations  you  specify  will  be  merged  with  the  widget's  default  transla 
tions  unless  you  are  using  the  default  #replace  directive.  However,  note  that  if  several 
resource  files  contain  translation  tables  for  the  same  widget  only  the  one  that  takes  priority 
according  to  resource  matching  and  precedence  will  have  any  effect  even  if  all  of  them 
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specify  ^augment  or  ^override.  This  is  because  the  translation  table  is  the  value  of  the 
resource,  and  the  last  value  specified  will  override  earlier  values. 

7.1 .7.2  Event  Sequences  Sharing  Initial  Events 

An  exception  to  this  rule  of  more  specific  translations  being  placed  earlier  in  the  translation 
table  occurs  with  event  sequences.  One  translation  can  contain  an  event  or  event  sequence 
that  appears  in  another  translation.  If  the  leading  event  or  event  sequence  is  in  common,  both 
will  operate  correctly.  For  example,  the  translations: 

<BtnlDown>, <BtnlUp> :     actionB { ) \n\ 
<BtnlDown>:  actionAO 

execute  actionA  ( )  when  button  1  is  pressed  and  actionB  ( )  when  it  is  then  released. 
This  is  true  regardless  of  which  translation  appears  first  in  the  table. 

This  is  the  reason,  alluded  to  in  Chapter  2,  why  it  is  not  possible  to  bind  two  different  actions 
to  a  single  and  a  double  click  of  the  same  button  in  the  same  widget  Specifying: 

<BtnlUp>(2):      quit()    \n\ 
<BtnlDown>, <BtnlUp>:       confirm () 

will  invoke  the  confirm  ()  action  on  a  single  click  and  both  the  confirm  ()  and 
quit  ( )  actions  on  a  double  click. 

This  behavior  was  a  design  decision  on  the  part  of  the  X  Consortium.  Otherwise,  the  Intrin- 
sics  could  never  dispatch  the  single-click  action  until  the  double-click  interval  had  passed, 
since  it  would  have  no  way  of  knowing  if  a  second  click  was  coming.  Applications  needing 
to  have  single  and  double  clicks  in  the  same  widget  must  do  so  by  designing  the  two  actions 
appropriately,  rather  than  relying  on  the  Translation  Manager  to  make  the  distinction. 

7.1.7.3  Event  Sequences  Sharing  Noninitial  Events 

If  a  noninitial  event  sequence  is  common  between  two  translations,  each  translation  will 
match  only  event  sequences  where  the  preceding  event  does  not  match  the  other  translation. 
Consider  the  translation: 

<BtnlDown>, <BtnlUp> :  actionB ( ) \n\ 

<BtnlUp>:  actionAO 

When  a  BtnlUp  event  occurs,  it  triggers  actionA  { )  only  if  not  preceded  by  BtnlDown. 

The  way  this  works  is  that  Xt  keeps  a  history  of  recent  events.  When  each  event  arrives,  Xt 
compares  this  event  and  its  immediate  history  to  the  event  sequences  in  a  translation  table. 
An  event  in  the  sequence  may  have  already  triggered  an  action,  but  that  is  irrelevent.  Any 
translation  whose  final  event  in  the  event  sequence  matches  the  current  event  and  whose  ear 
lier  event  sequence  matches  the  event  history  is  matched.  If  there  are  two  translations  that 
can  match  a  particular  event  sequence,  then  the  translations  are  considered  overlapping,  the 
latter  will  override  the  former,  and  Xt  will  print  a  run-time  warning  message  at  startup  (not 
waiting  for  the  overlapping  actions  to  be  invoked).  This  is  an  exception  to  the  rule  stated 
earlier  that  the  translation  manager  executes  the  first  match. 
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7.2  Accelerators 


Accelerators  are  simply  translation  tables  registered  to  map  event  sequences  in  one  widget  to 
actions  in  another.*  This  is  a  general  mechanism,  but  its  name  is  based  on  a  common 
use — adding  a  keyboard  interface  for  menus  and  Command  widgets — because  for  advanced 
users  a  keyboard  interface  is  often  faster. 

Every  widget  has  an  xtNaccelerators  resource,  inherited  from  the  Core  widget  class, 
so  the  actual  event-action  pairs  are  specified  through  the  resource  mechanism,  just  like  trans 
lations.  But  before  the  XtNaccelerators  resource  can  be  used,  the  application  must 
call  XtlnstallAccelerators  or  XtlnstallAllAccelerators  to  specify 
which  widget  will  be  used  as  the  source  of  the  actions  to  be  invoked,  and  which  will  be  the 
source  of  the  events  that  invoke  them. 

The  MIT  Intrinsics  documentation  refers  to  these  two  widgets  as  the  "source"  and  "destina 
tion."  This  can  be  confusing,  especially  since  the  arguments  are  referenced  in  reverse  order 
in  the  call  to  XtlnstallAccelerators: 


void  XtlnstallAccelerators (destination, 
Widget  destination; 
Widget  source; 


source) 


Just  remember  that  the  source  is  the  widget  whose  actions  you  want  executed,  and  the  desti 
nation  is  the  widget  you  want  the  events  to  be  gathered  in.  To  understand  the  use  of  the 
phrase  install  accelerators,  think  of  the  accelerators  as  the  XtNaccelerators  resource 
of  the  source  widget,  together  with  the  actions  of  that  widget,  and  the  destination  as 
the  widget  to  which  these  actions  are  transplanted  (i.e.,  "installed"). 

XtlnstallAccelerators  is  always  called  from  the  application.  (Widgets  never 
install  accelerators,  because  by  definition  they  don't  know  about  any  other  widgets.)  In 
applications,  this  can  be  done  any  time,  before  or  after  the  widgets  are  realized.  Just  before 
the  xtMainLoop  call  is  a  good  place. 

As  an  example,  we'll  add  accelerators  to  the  xboxl  application  from  Chapter  3.  This  applica 
tion  displays  two  Command  widgets  in  a  Box,  as  shown  in  Figure  7-1. 


Quit 

Press  Me 

Figure  7-1.  xboxl:  two  Command  widgets  in  a  Box 


*  Accelerators  made  their  debut  in  Release  3. 
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To  add  accelerators  requires  a  single  line  of  code — a  call  to  xt  installAccelerators, 
as  shown  in  Example  7-1. 

Example  7-1.  Installing  accelerators  in  an  application 

main(argc,  argv) 
int  argc; 
char  **argv; 
{ 

Widget  topLevel,  box,  quit; 


/*  allow  the  quit  widget's  actions  to  be  invoked  by  events 

*  in  box.  */ 
XtlnstallAccelerators (box,  quit) ; 

XtMainLoop () ; 
} 

The  actual  value  of  the  accelerator  table  is  set  through  the  resource  mechanism.  The  xt- 
Naccelerators  resource  is  set  for  the  widget  whose  actions  are  to  be  invoked  from 
another  widget  Xt  stores  this  accelerator  table,  in  compiled  form,  in  the  widget's  instance 
structure  when  the  widget  is  created.  When  the  application  calls  Xtlnstall 
Accelerators,  the  accelerator  table  stored  in  the  widget  is  merged  with  the  translation 
table  of  the  widget  that  will  be  capturing  the  events.  (If  xtRemoveAccelerators  is 
called,  the  original  translation  table,  prior  to  merging  with  the  accelerators  from  the  source 
widget,  is  restored.) 

Example  7-2  shows  a  possible  application-defaults  file. 

Example  7-2.  Specifying  the  XtNaccelerators  resource  from  the  application-defaults  file 

*quit. label:   Quit 
*pressme . label :   Press  me 
*quit .accelerators : \n\ 

<KeyPress>q:     set { )  notify () 

This  resource  setting  will  allow  a  q  typed  anywhere  in  the  Box  widget  that  comprises  the 
xboxl  application  window  to  invoke  the  quit  widget's  notify  ()  action  (which,  as  you 
may  recall  from  Section  2.4,  in  turn  invokes  the  Quit  callback  installed  by  the  application.) 
Notice  that  the  accelerators  are  specified  as  a  resource  of  the  source  widget,  even  though 
the  events  that  invoke  them  will  come  from  the  destination  widget 

There  are  some  differences  in  the  translation  tables  that  can  be  used  for  accelerators. 

•  Abbreviations  for  event  types  are  not  valid.  Only  the  event  names  that  were  shown  in 
column  1  of  Table  7-1  may  be  used  (although  key  works  in  place  of  KeyPress). 

•  The  None,  Meta,  Hyper,  Super,  Alt,  or  ANY  modifier  symbols  are  not  valid. 
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The  default  directive  for  accelerator  tables  is  faugment  rather  than  #replace.  If 
specified,  the  # replace  directive  is  ignored.  It  is  important  to  realize  that  accelerators 
are  merged  with  the  source  widget's  translations.  #override  thus  says  that  the  accel 
erators  take  priority  over  any  matching  translations  in  the  source  widget,  and  #augment 
says  that  the  accelerators  have  lower  priority. 

Parameters  passed  to  actions  must  be  quoted  with  double  quotes. 


7.2.1    Event  Propagation 

If  you  install  accelerators  in  the  box  widget  as  shown  in  Example  7-1,  you  will  notice  that 
even  though  the  destination  widget  is  box,  keyboard  input  will  also  be  accepted  in  the  chil 
dren  of  box,  including  not  only  the  quit  widget  but  also  the  pressme  widget  This  is 
because  of  a  characteristic  of  X  called  event  propagation. 

The  server  sends  to  the  client  only  the  types  of  events  the  client  selects.  Internally,  Xt  selects 
events  using  the  Xlib  call  XSelect Input.  From  a  Toolkit  application,  this  is  hidden 
because  the  translation  mechanism  automatically  selects  the  appropriate  event  types  speci 
fied  in  the  translation  table.  (As  we  will  see  in  Chapter  8,  More  Input  Techniques,  Xt  pro 
vides  a  low-level  event-handling  mechanism  that  exposes  event  selection  more  directly.) 

Event  selection  reduces  the  amount  of  network  traffic,  the  number  of  events  the  server  has  to 
generate,  and  the  number  of  unneeded  events  the  client  must  process  only  to  throw  away. 

Events  are  selected  on  a  per-window  basis.  Every  event  that  arrives  at  the  client  contains  the 
window  ID  of  the  window  it  was  selected  for.  (Non-maskable  events  are  the  exception,  since 
they  have  not  been  selected  by  a  window.) 

Pointer  and  keyboard  events  propagate  through  windows  that  have  not  selected  them,  as 
shown  below  in  Figure  7-2.  That  is,  if  the  pressme  widget's  window  has  not  selected 
KeyPress  events,  any  key  events  that  occur  in  that  window  will  be  passed  on  to  its  parent, 
the  box  widget  If  the  box  widget's  window  didn't  select  them  either,  they  would  be  passed 
on  to  the  window  created  by  the  top-level  Shell  widget,  and  so  on.  Events  propagate  through 
the  window  hierarchy  all  the  way  to  the  root  window,  until  they  reach  a  window  that  selected 
them.  (If  no  window  has  selected  them,  they  are  never  sent  by  the  server.)  Xt  treats  an  event 
that  originally  occurred  in  some  descendent  widget,  just  like  it  actually  happened  in  the 
widget  that  selected  the  event 
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Key  pressed  with 
pointer  in  pressme 
widget  . . . 


No  translation  for 
keyboard  events  on 
pressme  widget,  event 
propagated  to  box . . . 


box  widget  has  accelerator  for  keyboard 
events,  and  processes  event  propagated  from 
pressme.   box  has  installed  accelerator  that 
maps  keyboard  event  into  the  notify  and 
set  actions  of  the  quit  widget 


Figure  7-2.  Key  event  propagation  in  xbox 


Propagation  is  a  characteristic  of  ButtonPress,  ButtonRelease,  KeyPress,  Key- 
Release,  MotionNotif  y,  EnterNotif  y,  and  LeaveNotif  y  events  only.  As  men 
tioned  earlier,  keyboard  events  are  the  events  most  often  used  as  accelerators. 

In  the  version  of  xbox  we  just  looked  at,  keyboard  events  propagate  through  the  Command 
widgets  to  the  Box  widget,  because  they  are  not  selected  by  the  Command  widgets.  When 
they  reach  the  Box  widget,  they  match  the  events  specified  in  the  accelerator  table  and 
invoke  actions  from  the  quit  widget 

The  Command  widgets  have  a  default  translation  table  that  includes  pointer  button  events 
and  enter/leave  events.  Xt,  therefore,  selects  these  events  for  each  Command  widget  Before 
accelerators  are  installed,  the  Box  widget  has  no  translation  table  and  therefore  has  no  events 
selected  for  it  When  the  accelerators  are  installed,  the  accelerator  table  is  merged  with  the 
(nonexistent)  translation  table  of  the  Box  widget  and  becomes  the  Box's  translation  table. 
Xt  then  selects  keyboard  events  for  the  Box  widget 


208 


X  Toolkit  Intrinsics  Programming  Manual 


But  consider  the  resource  settings  in  Example  7-3. 

Example  7-3.  Conflicting  translations  and  accelerators 

*quit. label:      Quit 

*pressme . label :   Press  me 

*pressme .translations :   #override\n\ 

<KeyPress>p:     set()  notify () 
*quit . accelerators : \n\ 

<KeyPress>q:     set()  notify () 

No  key  event  will  propagate  through  a  widget  that  has  a  translation  for  any  key  event  With 
the  resource  settings  in  Example  7-3,  since  pressme  has  a  translation  for  the  p  key,  the  q 
key  will  not  propagate  through  the  widget  Therefore,  it  is  often  better  to  specify  all  key 
events  as  accelerators  and  install  them  on  a  common  ancestor. 

Accelerators  are  just  merged  into  translations — they  are  not  a  completely  different  mecha 
nism.  The  #augment  (default)  or  #override  directives  used  in  accelerator  tables  spec 
ify  whether  the  accelerator  should  override  or  augment  existing  translations  for  the  destina 
tion  widget  For  example,  if  box  had  a  translation  of  its  own  that  matched  the  event 
sequence  in  the  accelerator  installed  on  the  same  widget,  whether  the  translation  or  the  accel 
erator  would  be  invoked  depends  on  whether  #augment  (the  default)  or  #override  had 
been  specified  as  the  accelerator  directive.  (This  example  is  a  little  farfetched,  since  the  Box 
widget  defines  no  actions  or  translations — but  it  illustrates  the  point.) 

When  using  or  writing  widgets,  event  propagation  is  usually  important  only  for  accelerators, 
because  widgets  are  rarely  layered  in  such  a  way  that  any  of  the  ones  that  accept  input  are 
obscured. 


7.2.2   Installing  Accelerators  in  Multiple  Widgets 

If  you  want  to  install  accelerators  from  more  than  one  widget,  you  can  call  xtlnstall- 
Accelerators  once  for  every  widget  whose  actions  you  want  executable  from  the  desti 
nation.  Alternatively,  you  can  call  xtlnstallAHAccelerators  just  once  for  a 
whole  application,  specifying  the  application's  top-level  window  as  both  the  destination  and 
the  source.  xtlnstallAHAccelerators  recursively  traverses  the  widget  tree  rooted 
at  the  source,  and  installs  the  accelerators  of  each  widget  onto  the  destination. 

For  example,  to  install  accelerators  from  both  the  quit  and  pressme  widgets  onto  box, 
you  could  replace  the  call  to  xtlnstallAccelerators  shown  in  Example  7-3  with:* 

Example  7-4.  Installing  accelerators  from  both  command  widgets 
XtlnstallAllAccelerators (box,    box) ; 


*In  a  more  complex  application,  where  the  box  widget  was  not  the  main  window  but  only  a  subarea  containing  com 
mand  buttons,  you  might  instead  use  the  call: 

XtlnstallAllAccelerators (topLevel,    box) ; 
which  would  make  the  actions  from  only  the  widgets  contained  in  box  available  from  anywhere  in  the  application. 
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You  could  then  define  an  application-defaults  file  such  as  the  following: 

Example  7-5.  Accelerators  resource  settings  for  two  widgets 

*quit. label:   Quit 
*pressme . label :   Press  me 
*pressme . accelerators :   \n\ 

<KeyPress>p:     set()  notify () 
*quit .accelerators:   \n\ 

<KeyPress>q:     set()  notify () 

Note  that  if  there  were  any  actions  available  in  the  box  widget,  they  too  would  be  available 
for  specification  in  an  accelerator  resource  setting. 

Because  you  would  be  most  likely  to  specify  distinct  KeyPress  events  to  invoke  the 
actions  in  each  Command  widget,  you  would  normally  specify  each  accelerator  resource  sep 
arately,  as  shown  above.  But  in  the  unlikely  case  that  you  wanted  actions  of  multiple  Com 
mand  widgets  to  be  invoked  by  the  exact  same  event,  you  could  do  this  instead.  For 
example: 

*Command. accelerators :   \n\ 

<KeyPress>:   set()  notify () 

would  invoke  the  set  and  notify  actions  of  every  Command  widget,  but  not  of  widgets 
belonging  to  other  classes. 

Or  assuming  that  there  were  multiple  Box  widgets  in  an  application,  one  containing  options, 
and  the  other  commands,  you  might  specify  something  like  this: 

*optionsbox*accelerators :   \n\ 

<KeyPress>:   set()  notify () 

to  invoke  the  actions  of  every  Command  widget  in  optionsbox  only. 

The  point  is  that,  like  any  resource  setting,  an  accelerator  table  can  apply  to  only  one  widget, 
to  a  group  of  children  of  a  widget,  or  to  an  entire  class,  depending  on  how  you  identify  the 
widgets  for  which  you  are  setting  the  xtNaccelerators  resource. 

7.2.3    Defining  the  Accelerator  Table  in  the  Code 

If  you  want  to  install  a  default  accelerator  table  from  within  a  program,  you  must  follow  sim 
ilar  steps  to  those  used  for  translations,  but  with  the  following  differences: 

•  You  must  set  the  XtNaccelerators  resource  instead  of  XtNtranslations. 

•  Instead  of  using  xtParseTranslationTable  to  convert  the  ASCII  translation  table 
into  Xt's  internal  form,  use  XtParseAcceleratorTable. 

•  There  are   no  accelerator   equivalents   of  XtOverrideTranslations   or  xt- 
AugmentTranslations.  Instead  you  can  use  xtSetValues  and  use  the  acceler 
ator  directive  by  specifying  faugment  or  toverride. 
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7.2.4   The  display  accelerators  Method 

Xt  calls  the  source  widget's  display_accelerators  method  when  the  accelerators  are 
installed.  The  purpose  of  this  method  is  to  display  to  the  user  the  installed  accelerators.  The 
method  is  passed  a  string  representation  of  the  accelerator  table,  which  the  method  can  theo 
retically  manipulate  into  a  form  understandable  by  the  user. 

All  of  the  Athena  widgets  inherit  the  Core  widget's  display_accelerators  method 
by  initializing  the  appropriate  member  of  the  class  structure  to  xtlnheritDisplay- 
Accelerators.  This  default  method,  as  implemented  in  the  MIT  distribution,  does  noth 
ing. 
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More  Input  Techniques 


This  chapter  describes  how  to  handle  events  with  event  handlers,  and  how  to 
use  information  from  the  event  structure  inside  an  event  handler  or  action  rou 
tine.  It  also  describes  how  to  get  file,  pipe  or  socket  input,  how  to  use 
timeouts  to  call  a  function  after  a  delay  or  at  particular  intervals,  and  how  to 
use  work  procedures  to  do  background  processing.  Finally,  it  discusses  some 
low-level  features  of  Xt  lor  directly  interacting  with  the  event  queue. 
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In  addition  to  translations,  there  is  a  lower-level  mechanism  called  event  handlers.  Event 
handlers  can  be  used  from  application  or  widget  code.  An  event  handler  is  a  function  regis 
tered  with  xt  AddEventHandler  to  be  called  in  response  to  a  particular  event  or  group  of 
events  (but  not  an  event  sequence  or  combination,  as  is  possible  with  translations).  This  is  a 
low-level,  non-user-configurable  means  of  getting  events.  Event  handlers  provide  no  addi 
tional  capabilities  over  translations  and  actions.  But  they  allow  Xt  to  skip  the  step  of  search 
ing  a  translation  table  before  dispatching  the  event  to  an  event  handler.  This  speed  advantage 
is  possibly  significant  for  events  that  come  in  large  numbers,  such  as  pointer  motion  events, 
or  in  applications  with  large  translation  tables.  (Despite  this,  good  performance  in  tracking 
pointer  motion  can  be  achieved  with  translations.) 

Both  event  handlers  and  actions  are  passed  as  an  argument  the  actual  event  structure  that 
caused  them  to  be  invoked.  Many  event  handlers  and  actions  use  data  in  the  event  For 
example,  a  routine  handling  motion  events  may  want  to  obtain  the  current  pointer  position 
from  the  event  structure.  After  describing  how  to  add  and  remove  event  handlers,  we  discuss 
the  event  structures,  and  show  a  routine  that  uses  specific  event  data. 

Next,  this  chapter  discusses  three  ways  to  register  functions  Xt  will  call  for  input  other  than 
events,  since  some  programs  do  not  live  by  X  events  alone. 

•  XtAddlnput  registers  a  procedure  to  be  called  when  input  is  available  from  a  file  (or 
pipe  or  socket).   This  can  be  used  to  perform  code  necessary  when  reads,  writes,  or 
exceptions  are  detected. 

•  xtAddTimeOut  registers  a  function  to  be  called  at  a  particular  relative  time.  This  can 
be  used  to  implement  delays  or  to  execute  code  repeatedly  at  known  intervals. 

•  XtAddWorkProc  registers  a  work  procedure.  Work  procedures  are  called  when  input 
from  other  sources  is  not  available.  They  perform  background  tasks  while  the  application 
is  waiting  for  user  input. 

Finally,  we  provide  more  background  on  how  the  Toolkit  dispatches  events  from  xtMain- 
Loop,  and  describe  the  low-level  routines  that  can  be  used  to  construct  your  own  main  loop. 
We  also  describe  Xt's  event  filters,  which  are  controlled  by  flags  in  the  Core  class  structure. 
These  filters  tell  Xt  whether  or  not  to  compress  multiple  motion,  enter,  leave,  or  expose 
events  occurring  in  the  same  widget. 


More  Input  Techniques 


8.1   Event  Handlers 

An  event  handler  is  a  function  you  provide  to  handle  a  particular  type  of  event  or  group  of 
event  types.  You  register  this  function  with  a  call  to  xtAddE  vent  Handler,  specifying 
the  widget  in  which  the  events  are  to  be  monitored.  You  can  later  stop  the  function  from 
being  called  with  XtRemoveEventHandler.  On  any  widget,  you  can  register  as  many 
event  handlers  as  you  want,  each  for  the  same  or  for  different  types  of  events.  When  more 
than  one  routine  is  registered  for  an  event,  the  order  in  which  they  are  invoked  is  undefined. 

Event  handlers  are  infrequently  used  in  application  or  widget  code.  None  of  the  Athena 
widgets  uses  them,  and  only  xterm  and  xman,  out  of  the  40  applications  in  MIT's  core  distri 
bution  use  them.  As  mentioned  earlier,  event  handlers  are  useful  for  handling  high-volume 
events,  such  as  MotionNotify  events,  with  maximum  speed.  An  event  handler  for 
motion  events  would  probably  be  the  best  way  to  implement  a  drawing  program.  However, 
translation  tables  provide  good  speed  even  for  motion  events  on  most  systems. 

Event  handlers  would  also  be  useful  when  the  type  of  events  being  handled  changes  fre 
quently,  because  there  is  some  overhead  involved  in  compiling  and  merging  translation 
tables.  Event  handlers  can  also  be  used  to  handle  events  for  which  the  user-configurability  of 
translations  is  not  needed  or  wanted,  such  as  EnterWindow,  LeaveWindow,  Focus  In, 
and  Focus  Out  events. 

Another  possible  use  of  event  handlers  is  to  speed  the  handling  of  certain  events  when  there 
is  a  very  large  translation  table.  For  example,  editors  typically  have  a  large  number  of  trans 
lations  for  various  key  combinations.  If  an  editor  was  to  accept  pointer  motion  as  well  (to 
allow  drawing  of  simple  graphics),  it  might  pay  to  handle  motion  events  in  an  event  handler 
instead  of  through  translations. 

The  call  to  xtAddEventHandler  specifies  which  events  trigger  the  event  handler  func 
tion.  This  is  done  with  an  event  mask  argument*  In  an  event  mask,  each  bit  represents  one 
or  more  event  types.  Symbolic  constants  are  defined  by  Xlib  for  each  event  mask  bit.  Multi 
ple  types  of  events  can  be  selected  at  the  same  time  by  ORing  together  different  masks  with 
the  bitwise  OR  operator  (|).  Note  that  there  is  not  a  one-to-one  correspondence  between 
event  masks  and  event  types.  Some  event  masks  select  only  one  event,  but  others  select  mul 
tiple  events.  Furthermore,  several  of  the  masks  select  the  same  event  type,  but  specify  that  it 
be  delivered  only  when  it  occurs  under  special  conditions.  Table  8-1  shows  the  event  masks 
and  the  event  types  they  select. 

Table  8-1.  Event  Masks  and  Event  Types 


Event  Mask 

Event  Type 

KeyPressMask 
KeyReleaseMask 
ButtonPressMask 
ButtonReleaseMask 
OwnerGrabButtonMask 

KeyPress 
KeyRelease 
ButtonPress 
ButtonRe  lease 
n/a 

*The  event  mask  used  in  XtAddEventHandler  is  the  same  as  the  one  used  in  the  Xlib  call  XSelect  Input. 
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Table  8-1.  Event  Masks  and  Event  Types  (continued) 


Event  Mask 


Event  Type 


KeymapStateMask 

PointerMotionMask 

Point erMotionHintMask 

ButtonMotionMask 

ButtonlMotionMask 

Button2MotionMask 

ButtonSMotionMask 

Button4MotionMask 

ButtonSMotionMask 

EnterWindowMask 

LeaveWindowMask 

FocusChangeMask 

ExposureMask 

selected  in  GC  by 

graph ics_expose  component) 

ColormapChangeMask 

PropertyChangeMask 

VisibilityChangeMask 

ResizeRedirectMask 

StructureNotifyMask 


SubstructureNotifyMask 


SubstructureRedirectMask 


(always  selected) 
(always  selected) 
(always  selected) 
(always  selected) 
(always  selected) 


KeymapNotify 
MotionNotify 


EnterNotify 

LeaveNotify 

Focusln 

FocusOut 

Expose 

GraphicsExpose 

NoExpose 

ColormapNotify 

PropertyNotify 

VisibilityNotify 

ResizeRequest 

CirculateNotify 

ConfigureNotify 

DestroyNotify 

GravityNotify 

MapNotify 

ReparentNotify 

UnmapNotify 

CirculateNotify 

ConfigureNotify 

CreateNotify 

DestroyNotify 

GravityNotify 

MapNotify 

ReparentNotify 

UnmapNotify 

CirculateRequest 

Conf igureRequest 

MapRequest 

MappingNotify 

ClientMessage 

Select ionClear 

Select ionNot if y 

Select ionRequest 
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The  events  that  are  always  selected  are  called  nonmaskable  events.  These  can  also  be  han 
dled  with  an  event  handler,  but  not  by  specifying  them  in  the  event  mask.  An  argument  to  the 
XtAddE  vent  Handler  call,  non_maskable,  is  a  Boolean  value  that,  if  TRUE,  specifies 
that  the  event  handler  should  be  called  for  nonmaskable  events.  This  event  handler  then  must 
branch  according  to  which  of  the  seven  types  of  nonmaskable  events  it  is  passed.  A  typical 
nonmaskable  event  handler  is  shown  in  Section  8.1.2. 


8.1.1    Adding  Event  Handlers 

Event  handlers  are  added  with  a  call  to  xtAddEventHandler.  This  call  takes  five  argu 
ments:  the  widget  for  which  the  handler  is  being  added,  an  event  mask,  a  flag  that  specifies 
whether  or  not  this  handler  is  for  nonmaskable  events  (see  below),  the  name  of  the  handler, 
and  optional  client  data. 

XtAddEventHandler  may  be  called  before  or  after  a  widget  is  realized.  In  application 
code,  this  means  the  call  can  appear  anywhere  before  XtMainLoop.  In  a  widget,  XtAdd 
EventHandler  calls  are  placed  in  the  initialize  or  realize  methods. 

Example  8-1  shows  the  code  from  xterm  that  registers  an  event  handler  for  Focus  In  and 
FocusOut  events,  and  a  gutted  version  of  the  event  handler  itself. 

Example  8-1.  Registering  an  event  handler,  and  the  handler  function  itself 
extern   void   HandleFocusChange (); 

static  void  VTInitialize  (request,  new) 
XtermWidget  request,  new; 

111   { 


XtAddEventHandler (topLevel,  /*  widget  */ 

FocusChangeMask,   /*  event  mask  */ 
FALSE,  /*  non-maskable  events  */ 

HandleFocusChange,  /*  event  handler  */ 
(Opaque)NULL) ;     /*  client_data  */ 


/*ARGSUSED*/ 

void  HandleFocusChange (w,  unused,  event) 

Widget  w; 

register  XFocusChangeEvent  *event; 

caddr_t  unused;  /*  client_data  */ 

{ 

if (event->type  ==  Focusln) 

/*  process  Focusln  */ 


else  { 
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Example  8-1.  Registering  an  event  handler,  and  the  handler  function  itself  (continued) 

/*  process  FocusOut  */ 


In  typical  usage,  either  the  event  mask  argument  is  a  mask  and  the  non_maskable  argu 
ment  is  set  to  FALSE,  or  the  event  mask  argument  is  set  to  zero  and  non_maskable  is  set 
to  TRUE.  Example  8-1  demonstrated  the  former  case;  now  we'll  look  at  the  latter. 


8.1.2   Adding  Nonmaskable  Event  Handlers 

The  non_maskable  argument  of  XtAddE  vent  Handler  specifies  whether  the  speci 
fied  event  handler  should  be  called  in  response  to  the  events  that  can't  be  selected  as 
described  above.  The  nonmaskable  events  are  GraphicsExpose,  NoExpose, 
MappingNotify,  SelectionClear,  SelectionRequest,  Selection- 
Notify,  and  ClientMessage.  The  first  two  of  these  events  are  selected  using  the 
graphics_exposure  component  of  the  GC,  and  the  rest  are  always  sent  to  the  client 
whenever  they  occur.  MappingNotify  is  automatically  handled  by  Xt,  so  it  isn't  passed 
to  event  handlers  and  you  don't  need  to  worry  about  it  The  selection  events  are  described  in 
Chapter  10,  Inter-Client  Communications. 

Because  there  are  several  nonmaskable  event  types,  a  nonmaskable  event  handler  must  be 
sure  to  branch  according  to  the  type  of  event,  and  throw  away  any  event  types  not  handled. 
You  need  not  have  all  the  code  to  handle  all  the  types  in  a  single  event  handler.  Instead,  you 
can  handle  each  in  a  separate  handler,  each  registered  separately.  However,  each  would  still 
need  to  check  the  event  type  because  the  entire  list  of  them  would  be  called  for  every  non 
maskable  event 

Example  8-2  shows  the  registration  of  a  nonmaskable  event  handler  and  the  handler  itself, 
from  xman. 

Example  8-2.  Adding  a  nonmaskable  event  handler 

static   void 

Realize (w,  valueMask,  attributes) 

register  Widget  w; 

Mask  *valueMask; 

XSetWindowAttributes  * attributes; 

Illl  { 


XtAddEventHandler (w,  0,  TRUE, 

GExpose,  NULL);  /*  Get  Graphics  Exposures  */ 
}  /*  Realize  */ 

/*  ARGSUSED  */ 
static  void 
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Example  8-2.  Adding  a  nonmaskable  event  handler  (continued) 

GExpose (w, junk, event) 
Widget  w; 
caddr_t  junk; 
XEvent  *event; 
{ 

if  (event->type  ==  GraphicsExpose) 

Redisplay (w,  event,  NULL);   /*call  the  expose  method  directly*/ 
} 

This  event  handler  is  necessary  because  Xt  does  not  call  the  expose  method  in  response  to 
GraphicsExpose  events. 

8.1.3  Removing  Event  Handlers 

xtRemoveEventHandler  takes  the  same  arguments  as  XtAddEventHandler;  if 
there  are  parameter  mismatches,  the  call  is  quietly  ignored.  For  example,  the  client  data 
argument  may  be  used  to  distinguish  between  different  event  handlers;  if  the  client  data  argu 
ment  does  not  match  that  which  was  passed  in  the  XtAddEventHandler,  then  Xt 
RemoveEventHandler  will  do  nothing.  XtRemoveEventHandler  is  also  silent 
about  failing  to  remove  a  handler  that  was  never  added  or  an  incorrectly  specified  handler. 

8.1.4  Adding  Raw  Event  Handlers 

Xt  also  allows  you  to  add  event  handlers  without  actually  selecting  events.  These  are  called 
row  event  handlers,  and  are  added  with  xtAddRawEventHandler,  which  has  the  same 
calling  sequence  as  XtAddEventHandler.  The  event  mask  in  XtAddRawEvent 
Handler  indicates  which  events  the  handler  will  be  called  in  response  to,  but  only  when 
these  events  are  selected  elsewhere.  Raw  event  handlers  are  supported  mostly  because  they 
are  used  inside  Xt.  They  are  mentioned  here  only  for  completeness — you  are  unlikely  to 
need  them. 

A  raw  event  handler  might  be  used  to  "shadow"  another  event  handler  (both  added  with  the 
same  event  mask),  such  that  until  a  primary  event  handler  is  added,  the  shadow  handler  will 
never  be  called.  The  primary  handler  will  be  added  with  XtAddEventHandler,  which 
will  select  events,  and  then  both  handlers  will  be  called  when  the  appropriate  events  occur. 

However,  the  "shadowing"  technique  is  not  necessary  to  assure  that  multiple  calls  to  Xt 
AddEventHandler  don't  result  in  wasted  XSelect Input  calls  in  which  the  event 
mask  has  not  changed.  Xt  keeps  a  cache  of  the  event  masks  of  each  widget,  and  calls 
XSelect  input  only  when  it  is  necessary  to  change  the  window's  event  mask  attribute  in 
the  server. 

Raw  event  handlers  are  removed  with  a  call  to  XtRemoveRawEventHandler. 
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8.2  Writing  Routines  That  Use  Specific  Event  Data 

An  event  is  a  packet  of  information  that  the  server  sends  to  the  client.  Xlib  takes  this  packet 
from  the  network  and  places  it  into  an  XEvent  structure  and  places  it  on  a  queue  until  the 
client  program  requests  it.  Xt  requests  events  from  this  queue,  and  dispatches  the  event  to 
the  appropriate  action  routine  or  event  handler  for  the  widget  in  which  the  event  occurred. 
The  event  itself  is  passed  as  an  argument  to  the  routine.* 

Actually,  XEvent  is  a  C-language  union  of  many  event  structures  all  the  same  size  but  with 
some  different  field  names.  The  first  member  of  the  union,  and  of  any  of  the  individual  event 
structures,  is  the  event  type.  Table  8-2,  later  in  this  section,  lists  the  event  types  and  the 
matching  event  structure  types. 

Many  action  routines  are  intentionally  written  not  to  depend  on  the  detailed  information 
inside  any  particular  type  of  event,  so  that  the  user  can  specify  translations  to  call  the  action 
in  response  to  different  types  of  events.  For  example,  it  is  useful  for  an  action  routine  nor 
mally  triggered  by  a  pointer  click  to  work  when  called  in  response  to  a  key  instead.  Such  an 
action  should  not  depend  on  the  event  structure  fields  unique  to  button  events. 

However,  many  other  action  routines,  and  most  event  handlers,  do  use  the  detailed  informa 
tion  inside  event  structures.  The  first  member,  type,  identifies  which  type  of  event  this 
structure  represents,  and  hence  implies  which  other  fields  are  present  in  the  structure. 

To  access  event  structure  fields  other  than  type  you  need  to  cast  XEvent  into  the  appropri 
ate  event  structure  type.  If  you  are  expecting  only  one  type  of  event  to  trigger  this  action, 
then  you  can  simply  declare  the  argument  as  the  appropriate  type,  as  shown  in  Example  8-3. 

Example  8-3.  Casting  the  event  structure  by  declaring  action  routine  arguments 

static  void 
Turn (w,  event) 
TetrisWidget  w; 
XButtonEvent  *event; 
{ 

)/*  we  must  now  use  only  the  fields  in  XButtonEvent  */ 
if  (event->type  !=  ButtonPress) 
XtWarning( "TetrisWidget:  Turn  action  invoked\ 
by  wrong  event  type."); 


When  an  action  routine  or  event  handler  depends  on  the  fields  in  a  particular  event  structure, 
it  is  a  good  practice  to  check  the  event  type  in  that  action  unless  you  are  sure  that  the  user 
can't  change  the  translation  (and  thus  the  events  used  to  invoke  the  action). 

If  the  data  in  the  event  structure  is  important  to  an  action,  it  is  usually  better  to  write  the 
action  so  that  it  is  called  in  response  to  only  one  type  of  event  If  you  want  the  same  code 
called  for  two  event  types,  then  you  would  do  better  to  create  two  separate  translations  and 


*We'll  lex*  at  the  low-level  routines  Xt  provides  for  manipulating  the  event  queue  later  in  this  chapter.  For  now,  this 
simplified  discussion  is  sufficient 
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two  separate  actions  that  each  call  a  common  routine.  However,  it  is  sometimes  more  conve 
nient  to  have  an  action  called  by  two  different  events.  Example  8-4  shows  the  Toggle- 
Cell  action  from  the  BitmapEdit  widget,  which  is  called  in  response  to  either  Motion- 
Notify  or  Button? re ss  events.  This  action  inverts  a  pixel  in  the  bitmap  either  if  the 
pointer  is  clicked  on  a  cell  in  the  widget,  or  if  it  is  dragged  across  the  cell  with  the  pointer 
buttons  held  down. 

Example  8-4.  Handling  multiple  event  types  in  an  action  routine 

static  void 
ToggleCell (w,  event) 
BitmapEditWidget  w; 
XEvent  * event; 
{ 

static  int  oldx  =  -1,  oldy  =  -1; 

GC  gc; 

int  mode; 

int  newx,  newy; 

if  (event->type  ==  ButtonPress)  { 

newx  =  (w->bitmapEdit .cur_x  +  ( (XButtonEvent  *) event )->x)  / 

w->bitmapEdit . cell_size_in_pixels; 
newy  =  (w->bitmapEdit .cur_y  +  ((XButtonEvent  *)event)->y)  / 

w->bitmapEdit . cell_size_in_pixels; 

} 

else  if   (event->type  ==  MotionNotify)  { 

newx  =  (w->bitmapEdit .cur_x  +  ( (XMotionEvent  *)event)->x)  / 

w->bitmapEdit . cell_size_in_pixels; 
newy  =  (w->bitmapEdit . cur_y  +  ((XMotionEvent  *) event ) ->y)  / 

w->bitmapEdit . cell_size_in_pixels; 
} 
else 

XtWarning ("BitmapEdit :  ToggleCell  called  with  wrong 
event  type\n") ; 


Notice  that  some  code  is  repeated  to  cast  the  event  structure  to  the  two  different  event  types. 
With  the  current  MIT  implementation  of  Xlib,  the  positions  of  the  x  and  y  fields  in  the 
XButtonEvent  and  XMotionEvent  structures  are  the  same,  and  therefore  this  casting 
is  unnecessary.  However,  it  is  improper  to  depend  on  any  particular  implementation  of  Xlib. 
The  order  of  the  fields  in  one  of  these  events  could  be  different  in  a  vendor's  implementation 
of  Xlib. 


8.2.1    Event  Types  and  Structure  Names 

Table  8-2  lists  the  event  types  and  the  matching  event  structure  types.  The  event  descriptions 
in  the  table  will  give  you  a  general  idea  of  what  each  event  is  for.  Many  of  these  events  are 
not  often  used  in  applications,  and  more  of  them  are  automatically  handled  by  Xt.  We've 
already  discussed  how  to  use  the  most  common  event  types  and  their  abbreviations  in  transla 
tion  tables  in  Chapter  7,  Events,  Translations,  and  Accelerators.  Appendix  C,  Event 
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Reference  in  Volume  Five,  X  Toolkit  Intrinsic*  Reference  Manual,  provides  a  complete  refer 
ence  to  the  circumstances  under  which  each  event  is  generated,  what  it  is  for,  and  the  fields  in 
each  of  the  event  structures.  You  will  need  this  information  to  write  action  routines  that  use 
event-specific  data. 


Table  8-2.  Event  Types  and  Event  Structures 


Event  Type 


Structure 


Description 


KeyPress 

KeyRelease 

ButtonPress 

ButtonRelease 

KeymapNotify 

MotionNotify 

EnterNotify 

LeaveNotify 

Focusln 

FocusOut 

Expose 

GraphicsExpose 

NoExpose 

ColormapNotify 

PropertyNotify 

VisibilityNotify 

ResizeRequest 

CirculateNotify 
ConfigureNotify 
DestroyNotify 
GravityNotify 

MapNotify 
ReparentNotify 
UnmapNotify 
CirculateRequest 

ConfigureRequest 
MapRequest 

MappingNotify 
ClientMessage 
Select ionClear 
SelectionNotify 
Select ionRequest 


XKeyPressedEvent 

XKeyReleasedEvent 

XButtonPressedEvent 

XButtonReleasedEvent 

XKeymapEvent 

XPointerMovedEvent 

XEnterWindowEvent 

XLeaveWindowEvent 

XFocusInEvent 

XFocusOutEvent 

XExposeEvent 

XGraphicsExposeEvent 

XNoExposeEvent 

XColormapEvent 

XPr ope rtyE vent 

XVisibilityEvent 

XResizeRequestEvent 

XCirculateEvent 
XConfigureEvent 
XDestroyWindowEvent 
XGravityEvent 

XMapEvent 
XReparent Event 
XUnmapEvent 
XCirculateRequest Event 

XConfigureRequestEvent 
XMapRequest Event 

XMappingEvent 

XClientMessageEvent 

XSetSelectClearEvent 

XSelectionEvent 

XSelectionRequestEvent 


Key  pressed 
Key  released 
Pointer  button  pressed 
Pointer  button  released 
State  of  all  keys  when  pointer  entered 
Pointer  motion 
Pointer  entered  window 
Pointer  left  window 
This  window  is  now  keyboard  focus 
This  window  was  keyboard  focus 
Part  of  window  needs  redrawing 
Source  of  copy  unavailable 
Source  of  copy  available 
Window's  colormap  changed 
Property  value  changed 
Window  has  been  obscured 
Redirect  resize  request  to  window 
manager 

Stacking  order  modified 
Window  resized  or  moved 
Window  destroyed 

Window  moved  due  to  win  gravity 
attribute 

Window  mapped 
Window  reparented 
Window  unmapped 
Redirect  stacking   order  change   to 
window  manager 

Redirect  move  or  resize  request  to 
window  manager 

Redirect  window  map  request  to  win 
dow  manager 

Keyboard  mapping  changed 
Client-dependent 
Current  owner  is  losing  selection 
Selection  is  ready  for  requestor 
Request  for  selection  to  current  owner 
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8.3  File,  Pipe,  and  Socket  Input 

xtAddlnput  allows  a  program  to  obtain  input  from  a  file.  This  is  not  merely  reading  the 
file  once,  but  monitoring  it  for  further  activity.*  Under  UNIX  this  can  be  used  to  get  input 
from  pipes  and  sockets,  since  they  are  variations  of  files.  We  will  demonstrate  getting  file 
and  pipe  input  in  this  section. 

The  XtAddlnput  routine  takes  four  arguments:  a  file  descriptor,  a  flag  (see  below),  your 
function,  and  client_data. 

xtAddlnput  returns  an  ID  that  uniquely  identifies  the  XtAddlnput  request.  You  can 
use  the  ID  to  cancel  the  request  later  with  xt Remove  Input. 

One  argument  of  XtAddlnput  is  a  file  descriptor  (this  file  must  be  open  before  calling 
xtAddlnput).  Since  implementation  of  files  varies  between  operating  systems,  the  actual 
contents  of  the  parameter  passed  as  the  file  descriptor  argument  to  these  routines  is  operating 
system-dependent.  Therefore,  this  code  is  inherently  nonportable. 

Possible  values  for  the  mask  and  their  meanings  are  as  shown  in  Table  8-3. 
Table  8-3.  Other  Input  Source  Masks 


Mask 


XtlnputReadMask 
XtlnputWriteMask 
Xt  InputExceptMask 
Xt  InputNoneMask 


Description 


File  descriptor  has  data  available 
File  descriptor  available  for  writing 
I/O  errors  have  occurred  (exceptions) 
Never  call  function  registered 


Calling  these  argument  values  masks  is  something  of  a  misnomer,  since  they  cannot  be  ORed 
together.  However,  you  can  call  XtAddlnput  additional  times  to  register  a  separate  func 
tion  for  each  of  these  masks  on  the  same  file  descriptor. 

8.3.1    Getting  File  Input 

In  Example  8-5,  a  program  called  xfileinput  reads  new  characters  from  a  file  whenever  they 
appear.  In  other  words,  the  program  will  initially  print  to  the  standard  output  the  contents  of 
the  file  specified  on  the  command  line,  and  it  will  print  any  characters  that  are  later  appended 
to  that  file.  Try  the  program  xfileinput  as  follows: 

echo  "test  string"  >  testfile 

xfileinput  testfile  & 

echo  "more  text"  »  testfile 


*A  bug  in  R3  prevented  the  function  registered  with  XtAddlnput  from  being  called  unless  normal  X  events  were 
available.  This  effectively  makes  the  feature  useless  under  R3.  The  examples  in  this  section  work  under  R4  only. 


224  X  Toolkit  Intrinsics  Programming  Manual 


A  program  such  as  this  functions  similarly  to  the  UNIX  command  tail  -f.  It  could  be  used  to 
monitor  system  log  files,  or  other  similar  files  that  grow. 

The  code  shown  in  Example  8-5  opens  the  file  and  calls  XtAddlnput  in  main.  The 
get_f  ile_input  function  registered  with  XtAddlnput  reads  and  prints  characters 
from  the  file.* 

Example  8-5.  Getting  file  input  with  XtAddlnput 
/*    header    files    */ 


/*  ARGSUSED  */ 

get_file_input (client_data,  fid,  id) 

caddr_t  client_data;    /*  unused  */ 

int  *fid; 

Xtlnputld  *id; 

{ 

char  buf [BUFSIZ] ; 

int  nbytes; 

int  i; 

if  ((nbytes  =  read(*fid,  buf,  BUFSIZ))  ==  -1) 
perror ("get_file_input") ; 

if  (nbytes) 

for  (i  =  0;  i  <  nbytes;  i++) 

putchar (buf [i] ) ; 
} 

main(argc,  argv) 
int  argc; 
char  **argv; 
{ 

Widget  topLevel,  goodbye; 

FILE  *fid; 

String  filename; 

topLevel  =  Xtlnitialize (argv [0] ,  "XFilelnput",  NULL, 
0,  sargc,  argv) ; 

if  (argv[l]  =  =  NULL)  { 

fprintf (stderr,  "xfileinput:  filename  must  be  specified  on\ 
command  line.Xn"); 

exit  (1) ; 
} 
filename  =  argv[l]; 


/*  open  file  */ 

if  ((fid  =  f open (filename,  "r") )  ==  NULL) 

fprintf (stderr,  "xfileinput:  couldn't  open  input  file") ; 


*Note  that  the  code  for  opening  and  reading  files  is  probably  not  portable  to  operating  systems  other  than  UNIX. 
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Example  8-5.  Getting  file  input  with  XtAddlnput  (continued) 

/*  register  function  to  handle  that  input,  NULL  arg 

*  is  client_data  */ 
XtAddlnput (fileno (fid) ,  XtlnputReadMask,  get  file  input,  NULL); 


XtRealizeWidget (topLevel) ; 
XtMainLoopO  ; 


I 


The  function  registered  with  XtAddlnput  is  called  with  client_data  (used  for  passing 
in  any  application  data),  a  pointer  to  the  file  descriptor,  and  the  ID  of  the  XtAddlnput 
request  You  can  use  a  call  to  Xt  Remove  Input  in  the  function  registered  with  XtAdd 
lnput  if  that  function  is  only  to  be  called  once.  One  argument  of  the  xt Remove  Input 
call  is  the  ID  of  the  XtAddlnput  request* 

8.3.2   Getting  Pipe  Input 

The  code  to  get  pipe  input  is  almost  identical  to  the  code  just  shown  that  gets  file  input.  The 
only  difference  is  that  we  us&popen  instead  of f open,  and  change  the  various  error  messages. 
Now  instead  of  treating  the  command-line  argument  as  a  filename,  it  is  treated  as  a  program 
run  under  a  shell.  This  program's  output  is  piped  into  our  application.  For  example,  here  is 
an  example  of  how  to  invoke  this  version  of  xpipeinput: 

spike%    xpipeinput    "cal    11    1989" 

November    1989 
S      M   Tu      W   Th      F      S 
1234 
5       6      7      8       9    10    11 
12    13    14    15    16    17    18 
19   20    21    22    23    24    25 
26   27    28    29    30 
(Program  continues  to  monitor  pipe  for  further  input  until  application  exits.) 

Note  that  xpipeinput  is  reading  the  string  "cal  11  1989"  from  the  command  line,  invoking  a 
shell,  running  the  command  specified  by  the  string  under  this  shell,  reading  the  output  of  the 
shell,  and  then  printing  it  on  the  standard  output  This  is  an  easy  way  to  use  all  kinds  of  shell 
scripts  and  utilities  from  within  a  program. 

If  you  want  your  application  to  accept  standard  input,  this  is  even  easier.  Remove  the  code 
that  reads  the  filename  from  the  command  line  and  remove  the  popen  call  to  open  the  pipe, 
since  the  pipe  from  stdin  is  always  open.  Then  use  the  XtAddlnput  shown  in  Example 
8-6. 


*Under  the  beta  release  of  R4,  the  function  registered  with  XtAddlnput  ii  called  very  frequently  even  when  no 
new  input  is  available.  The  examples  shown  work,  but  they  load  down  the  system  much  more  than  necessary.  It  is 
difficult  to  tell  whether  this  is  a  bug  or  the  intended  behavior.  If  this  "feature"  is  still  present  in  your  version  of  Xt, 
you  may  wish  to  add  your  input  handler  periodically  using  timeouts  (to  be  described  next),  and  have  the  input  han 
dler  remove  itself  each  time. 
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Example  8-6.  Reading  stdin  from  an  Xt  application 

XtAddlnput (f ileno (stdin) ,  XtlnputReadMask,  get_f ile_input ,  NULL); 

Once  you  have  done  this,  you  can  invoke  xpipeinput  as  follows: 

spike%  cal  11  1989  I  xpipeinput 

November    1989 
S      M   Tu      W   Th      F      S 
1234 
5      6      7      8      9    10    11 
12    13    14    15    16    17    18 
19   20    21    22    23    24    25 
26    27    28    29    30 
(Program  continues  to  monitor  pipe  for  further  input  until  application  exits.) 

Note  that  in  this  case,  xpipeinput  is  reading  directly  from  stdin,  and  then  printing  the  output 
to  stdout.  With  more  code,  it  could  display  this  calendar  in  a  Text  widget  instead. 


8.4  Timeouts 

A  program  may  wish  to  be  notified  when  a  period  of  time  has  elapsed,  while  being  able  to  do 
other  things  during  that  time.  For  example,  a  clock  widget  requires  a  periodic  nudge  to 
change  the  time  it  is  displaying,  but  must  also  be  able  to  redisplay  itself  at  any  time  in  case  of 
exposure. 

This  is  done  by  using  xtAddTimeOut.  This  routine  is  passed  a  time  interval  in  milli 
seconds,  and  the  address  of  a  function  to  be  invoked  when  the  time  interval  expires.  As 
usual,  a  clie/it_data  argument  can  also  be  registered.  The  xtAddTimeout  routine 
returns  a  handle  that  can  be  used  to  cancel  the  timeout  before  it  triggers,  if  necessary. 

A  timeout  is  automatically  removed  when  the  registered  function  is  called.  Therefore,  to 
have  a  function  called  repeatedly,  every  N  milliseconds,  the  registered  function  must  add  the 
timeout  again  by  calling  XtAddTimeOut. 

One  of  the  major  applications  of  timeouts  other  than  clocks  is  in  real-time  games.  Figure  8-1 
shows  the  appearance  of  a  game  called  xtetris  after  it  has  been  played  for  a  couple  of  min 
utes. 

The  object  of  the  game  is  to  steer  falling  blocks  and  rotate  them  so  that  they  fit  well  into  the 
existing  fallen  blocks.*  The  game  is  over  when  the  blocks  pile  up  to  the  top  of  the  window. 
Every  time  a  row  is  completely  filled,  it  is  removed  and  all  the  blocks  above  it  move  down 
one  row.  The  window  in  which  the  blocks  fall  is  a  specialized  widget  This  game  uses 
timeouts  to  time  the  falling  of  the  blocks. 


*This  game  is  provided  with  the  example  joarce  code.  It  is  an  X  version  of  a  game  available  on  the  Macintosh  called 
Tetris,  trademark  of  AcademySoft-ELORG,  copyright  and  trademark  licensed  to  Andromeda  Software  Ltd.  The  ong- 
inal  concept  of  the  game  is  by  Alexi  Pazhimov  and  Vadim  Gerajimov. 
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Figure  8-1.  xtetris  in  play 

Example  8-7  is  an  excerpt  from  a  widget  used  by  xtetris  that  adds  the  timeout  The  timeout 
function  itself  is  also  shown. 

Example  8-7.  xtetris:  registering  a  timeout,  and  the  timeout  function 

static  Xtlntervalld  timer; 

static  void 
StartBlock(w) 
BitmapEditWidget  w; 
{ 

w->bitmapEdit.cur_x  =  9; 

w->bitmapEdit .cur_y  =  0; 
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Example  8-7.  xtetris:  registering  a  timeout,  and  the  timeout  function  (continued) 

w->bitmapEdit.type  =  PickType(); 
DrawBlock  (w,  DRAW)  ; 

timer  =  XtAddTimeOut  (w->bitmapEdit  .delay,  MoveDown,  w)  ; 
} 

static  void 

MoveDown  (w) 

BitmapEditWidget  w;      /*  client_data  */ 

{ 

if  (CanMoveDown  (w)  )  { 

DrawBlock  (w,  UNDRAW); 

w->bitmapEdit  .  cur_y++; 

DrawBlock  (w,  DRAW)  ; 

CopyBlock  (w)  ; 

timer  =  XtAddTimeOut  (w->bitmapEdit  .delay, 

MoveDown,  w)  ; 
}  else  {  /*block  has  hit  bottom  or  other  stationary  blocks*/ 

UpdateCellArray  (w)  ; 

KillRows(w)  ; 

Score  (w)  ; 

w->bitmapEdit  .delay  -=  5; 

StartBlock(w)  ; 


Notice  that  a  timeout  function  is  called  with  only  one  argument,  cl±ent_data.  Inside  a 
widget,  this  argument  is  commonly  used  to  pass  in  the  widget  instance  pointer.  Also  notice 
that  every  time  a  block  hits  the  bottom,  the  instance  variable  delay  is  decremented  by  5, 
which  reduces  the  number  of  milliseconds  of  delay  used  when  XtAddTimeOut  is  next 
called.  In  other  words,  the  blocks  fall  progressively  faster. 

xtetris  also  needs  to  remove  a  timeout  in  one  of  its  routines.  The  user  can  "drop"  a  block  to 
score  extra  points  (if  there  is  enough  time).  Whenever  a  block  is  dropped,  the  block  is  imme 
diately  moved  down  as  far  as  it  will  go,  and  a  new  block  is  started.  If  the  Drop  action  did 
not  remove  the  timeout,  the  new  block  would  be  started  with  a  new  timeout  while  an  existing 
timeout  was  already  in  force.  This  would  mean  that  the  MoveDown  timeout  function  would 
be  invoked  twice  in  quick  succession  when  each  of  these  timeouts  expired.  Example  8-8 
shows  the  XtRemoveTimeOut  call  in  the  Drop  action. 

Example  8-8.  xtetris:  calling  XtRemoveTimeOut 

static  void 
Drop  (w,  event) 
BitmapEditWidget  w; 
XButtonEvent  *event; 
{ 

XtRemoveTimeOut  (timer)  ; 

while  (CanMoveDown  (w)  )  { 

DrawBlock  (w,  UNDRAW); 
w->bitmapEdi  t  .  cur_y++  ; 
DrawBlock  (w,  DRAW); 
CopyBlock  (w)  ; 
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Example  8-8.  xtetris:  calling  XtHemoveTimeOut  (continued) 

UpdateCellArray (w) ; 
KillRows(w) ; 
score++; 
Score (w) ; 

w->bitmapEdit .delay  -=  5; 
StartBlock(w) ; 
} 

Notice  that  the  timer  ID  returned  from  the  calls  to  xtAddTimeOut  is  a  global  variable. 
Xt  calls  the  timeout  function  with  only  one  argument,  and  that  argument  passes  in  the  widget 
instance  pointer.  We  could  have  created  a  structure  containing  the  widget  instance  pointer 
and  the  timer  ID  and  passed  its  pointer  to  the  timeout  function.  But  this  wouldn't  help, 
because  the  action  routine  in  which  we  remove  the  timeout  is  passed  with  no 
client_data  argument.  (It  has  string  parameters,  but  these  are  hardcoded  in  the  actions 
table.)  Therefore,  we  are  forced  to  have  a  global  variable  for  the  timer  ID. 

Note  that  between  the  time  when  the  timeout  is  registered  and  when  it  triggers,  the  applica 
tion  processes  events  in  xtMainLoop.  Therefore,  all  the  widget's  actions  and  expose 
method  are  in  operation  between  the  invocations  of  the  timeout  function. 


8.4.1    Visibility  Interest 

Timeouts  operate  regardless  of  the  visibility  of  the  application.  Since  it  is  pointless  for  most 
games  to  continue  operating  while  obscured,  it  makes  sense  to  remove  the  game's  timeouts 
when  the  game  is  partially  or  fully  obscured  (or  iconified).  To  do  this,  you  can  set  the  vis  - 
ible_interest  field  in  the  Core  class  structure  to  TRUE,  and  then  check  the  visible 
field  of  the  Core  instance  structure  periodically.  When  the  application  is  fully  obscured,  you 
add  a  separate  timeout  to  continue  testing  the  visibility  status.  When  the  visibility  status  is 
satisfactory  once  again,  the  game  can  add  its  timeout  again.  All  these  changes  are  in  the 
widget's  .c  file.  First  we  set  the  visible_interest  field  to  TRUE  in  the  Core  structure: 

BitmapEditClassRec  bitmapEditClassRec  =  { 
{ 
/*  core  class  fields  */ 


/*  visible_interest          */  TRUE, 


Second  we  change: 

timer   =   XtAddTimeOut (w->bitmapEdit .delay,    MoveDown,    w) ; 
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to: 

if  (w->core. visible  ==  FALSE) 

timer  =  XtAddTimeOut (250,  CheckVisibility,  w)  ; 
else 

timer  =  XtAddTimeOut (w->bitmapEdit .delay,  MoveDown,  w)  ; 

And  finally,  we  add  the  timeout  function  that  continues  to  check  the  visibility  status. 

static   void 

CheckVisibility (w) 

BitmapEditWidget  w;     /*  client_data  */ 

{ 

if  (w->core. visible  ==  FALSE) 

timer  =  XtAddTimeOut (250,  CheckVisibility,  w) ; 
else 

timer  =  XtAddTimeOut (w->bitmapEdit .delay, 

MoveDown,  w) ; 
} 

Unfortunately,  the  Core  visible  field  is  TRUE  even  if  a  tiny  sliver  of  the  widget  is  visible. 
The  only  way  to  get  around  this  is  to  add  an  event  handler  (or  translation)  for 
VisibilityNotify  events,  and  to  add  an  instance  variable  to  maintain  the  visibility 
state.  The  event  handler  or  action  would  check  the  state  field  of  the  event,  and  put  the 
game  into  hibernation  if  the  window  is  only  partially  obscured.  However,  this  approach  has 
the  opposite  problem;  it  disables  the  game  even  when  only  a  sliver  is  obscured. 

There  is  nothing  you  can  do  about  the  game  continuing  to  run  while  being  moved  or  resized 
with  the  window  manager.  However,  using  the  Core  visible_interest  field  does  stop 
the  game  when  it  is  iconified. 


8.5  Work  Procedures 


A  work  procedure  is  an  application-supplied  function  that  is  executed  while  an  application  is 
idle  waiting  for  an  event  Work  procedures  are  registered  with  xtAddWorkProc.  They 
can  perform  any  calculation  that  is  short  enough  that  the  routine  will  return  in  a  small  frac 
tion  of  a  second.  If  the  work  procedure  is  too  long,  the  user's  response  time  will  suffer. 

If  a  work  procedure  returns  TRUE,  then  Xt  will  remove  it  and  it  will  not  be  called  again.  But 
if  one  returns  FALSE,  it  will  be  called  repeatedly  every  time  there  is  idle  time,  until  the  appli 
cation  calls  XtRemoveWorkProc.  A  work  procedure  would  return  TRUE  if  it  performs  a 
one-time  setup  such  as  creating  a  pop-up  widget  It  would  return  FALSE  if  it  were  continu 
ously  updating  a  disk  file  as  security  against  a  system  crash  or  server  connection  failure. 

You  can  register  multiple  work  procedures,  and  they  will  be  performed  one  at  a  time.  The 
most  recent  work  procedure  added  has  the  highest  priority.  Therefore,  for  example,  if  you 
want  to  create  ten  pop-up  widgets  during  idle  time,  you  should  add  ten  work  procedures.  The 
pop  up  that  you  expect  to  need  first  should  be  added  in  the  last  work  procedure  registered. 

The  call  to  register  a  work  procedure  is  shown  in  Example  8-9. 
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Example  8-9.  Registering  an  Xt  Work  Procedure 
static   Boolean    create_popup () ; 


main(argc,    argv) 
int   argc; 
char    **argv; 
{ 

XtWorkProcId  popup_work_ID 

Widget    topLevel; 


/*    Xtlnitialize,    create   widgets,    etc.    */ 
popup_work_ID   =   XtAddWorkProc (create_popup,    topLevel) 


XtRealizeWidget (topLevel) ; 
XtMainLoopO  ; 
} 

Notice  that  xtAddWorkProc  returns  an  ID  of  type  XtWorkProcId,  which  is  used  only 
in  any  subsequent  call  to  xtRemoveWorkProc.  You  can  cast  the  returned  value  to  void 
if  you  do  not  intend  to  explicitly  remove  the  work  procedure. 

The  client_data  argument  passes  application  data  into  the  work  procedure.  It  is  used 
just  like  the  same  argument  in  callback  functions.  Example  8-10  shows  a  work  procedure  to 
create  a  pop-up  widget. 

Example  8-10.  A  work  procedure  to  create  a  pop-up  widget 
Widget    pshell; 

/*  work  procedure  */ 
Boolean 

create_popup (parent) 
Widget  parent; 
{ 

Widget  dialog,  dialogDone; 

pshell  =  XtCreatePopupShell ( 
"pshell", 

transient She HWidget Class, 
parent, 
NULL, 
0 
); 

dialog  =  XtCreateManagedWidget ( 

"dialog",  /*  widget  name  */ 

dialogWidgetClass,   /*  widget  class  */ 
pshell,  /*  parent  widget  */ 

NULL,  /*  argument  list  */ 

0  /*  arglist  size  */ 
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Example  8-10.  A  work  procedure  to  create  a  pop-up  widget  (continued) 

dialogDone  =  XtCreateManagedWidget ( 

"dialogDone",        /*  widget  name  */ 
commandWidgetClass,  /*  widget  class  */ 
dialog,  /*  parent  widget  */ 

NULL,  /*  argument  list  */ 

0  /*  arglist  size  */ 

XtAddCallback (dialogDone,  XtNcallback,  DialogDone,  dialog); 
return  (True)  ;  /*  makes  Xt  remove  this  work  proc  automatically  */ 

Remember  that  Xt  cannot  interrupt  a  work  procedure  while  it  is  running;  the  procedure  must 
voluntarily  give  up  control  by  returning,  and  it  must  do  so  quickly  to  avoid  slowing  user 
response. 


8.6  Low-level  Management  of  the  Event  Queue 

As  you  know,  an  X  Toolkit  application  simply  calls  xtMainLoop  to  begin  processing 
events.  XtMainLoop  itself  is  quite  simple:  it  consists  of  an  infinite  loop  calling  two 
lower-level  routines,  XtNextEvent  and  xtDispatchEvent.  XtNextEvent  extracts 
the  next  event  from  the  application's  event  queue;  XtDispatchEvent  actually  uses  the 
event  to  invoke  the  appropriate  actions  or  event  handlers.  (The  callbacks  for  pseudo-events 
registered  by  XtAddlnput  and  xtAddTimeOut  are  dispatched  directly  by  XtNext 
Event;  if  no  events  are  available,  XtNextEvent  flushes  the  X  output  buffer,  and  calls 
any  work  procedures  registered  by  xtAddWorkProc.) 

An  application  can  provide  its  own  version  of  this  loop,  as  shown  in  Example  8-11.  For 
example,  it  might  test  some  application-dependent  global  flag  or  other  termination  condition 
before  looping  back  and  calling  XtNextEvent.  Or  for  fine-grained  debugging,  it  might  be 
worthwhile  to  insert  a  routine  that  prints  out  each  event  dispatched. 

II     Example  8-11.  Skeleton  of  a  custom  main  loop 

void  MyMainLoopO 
{ 

XEvent  event; 

for  (;;)  { 

XtNextEvent (Sevent) ; 
XtDispatchEvent (&event) ; 

/*  Do  application-specific  processing  here  */ 
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8.6.1    XtPending  and  XtPeekEvent 

All  event  sources  depend  on  idle  time  in  the  application  to  return  to  XtMainLoop  where  Xt 
can  check  to  see  if  input  is  available  from  any  of  the  various  sources.  If  an  application  has 
long  calculations  to  make,  the  program  may  not  return  to  XtMainLoop  frequently  enough 
to  detect  important  input  in  a  timely  fashion.  The  application  itself  should,  if  possible,  sus 
pend  lengthy  calculations  for  a  moment  to  check  whether  input  is  available.  Then  it  can 
determine  whether  to  process  the  input  before  continuing,  or  finish  the  calculation. 

To  detect  whether  input  from  any  input  source  is  available,  you  can  call  XtPending.  This 
function  returns  a  mask  composed  of  a  bitwise  OR  of  the  symbolic  constants  xtiMXEvent, 
xtiMTimer,  and  xtlMAlternatelnput.  These  constants  refer  to  X  events,  timer 
events,  and  alternate  input  events,  respectively. 

To  find  out  what  the  first  event  in  the  queue  contains,  you  can  call  XtPeekEvent.  This 
function  returns  an  event  structure  without  removing  the  event  from  Xlib's  queue. 

It  is  also  possible  to  remove  and  process  a  single  event  xtProcessEvent  combines 
some  (but  not  all)  of  the  functions  from  XtNextEvent  and  XtDispatchEvent.  That 
is,  while  XtNextEvent  takes  the  next  event  from  the  queue,  whatever  it  is,  XtProcess 
Event  allows  you  to  specify  as  a  mask  a  bitwise  OR  of  the  symbolic  constants  xt- 
iMXEvent,  XtiMTimer,  and  XtlMAlternatelnput.  This  lets  you  select  only  some 
of  these  event  types  for  processing.  In  addition,  XtProcessEvent  actually  calls  Xt 
DispatchEvent  to  dispatch  X  events,  so  only  this  one  call  is  necessary. 


8.6.2    Event  Filters 

As  you  saw  in  Chapter  5,  Inside  a  Widget,  the  class  structure  contains  three  Boolean  fields 
that  control  Xt's  event  filters.  These  are  compress_motion,  compress_enter- 
leave,  and  compress_exposure.  Widgets  set  these  fields  to  TRUE  when  repeated 
events  of  these  types  are  unwanted.  Each  would  be  used  in  different  situations.  If  turned  on, 
they  tell  Xt  to  search  Xlib's  queue  for  a  certain  event  sequence  and  then  remove  repeated 
occurrences  of  those  events  from  the  queue. 

When  the  compress_motion  filter  is  set  to  TRUE,  and  there  is  a  series  of  Motion- 
Notify  events  on  the  queue  (which  occurs  when  the  application  gets  behind  in  processing 
them),  the  filter  throws  out  all  but  the  last  one  (the  most  recent  position).  This  is  useful  for 
widgets  that  need  the  most  up-to-date  position  but  do  not  need  a  complete  history  of  pointer 
positions. 

The  compress_enterleave  filter  throws  out  all  EnterNotify/LeaveNotify 
pairs  on  the  same  window  in  which  there  are  no  intervening  events.  This  would  be  used  by  a 
widget  that  is  interested  in  enter  and  leave  events,  but  not  if  the  application  falls  behind.  For 
example,  even  the  Command  widget  sets  compress_enterleave  to  TRUE.  It  highlights 
its  border  when  the  pointer  enters,  and  clears  it  when  the  pointer  leaves.  But  if  for  some  rea 
son  the  widget  falls  behind  and  has  not  highlighted  the  border  by  the  time  the  Leave- 
Notif  y  event  arrives  with  no  intervening  events,  the  border  will  not  be  highlighted.  To  see 
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this,  move  the  pointer  quickly  across  a  large  panel  of  Command  widgets  such  as  in  xmh,  and 
you  will  see  that  not  all  of  them  draw  and  then  undraw  the  border. 

When  the  compress_exposure  filter  is  set  to  FALSE,  a  widget's  expose  method  is 
called  repeatedly  in  response  to  each  Expose  event  in  a  contiguous  series.  Each  event 
would  normally  specify  a  different  rectangle  of  the  widget  that  needs  redrawing.  With  com- 
press_exposure  set  to  TRUE,  however,  this  contiguous  series  is  compressed  into  a  single 
modified  Expose  event  and  the  expose  method  is  called  only  once.  This  modified 
Expose  event  contains  the  bounding  rectangle  of  the  union  of  all  the  rectangles  in  the  indi 
vidual  events.  In  addition,  only  when  compress_exposure  is  TRUE  is  the  expose 
method  passed  an  Xlib  Region  that  describes  in  detail  the  area  exposed.  All  widgets  except 
those  that  display  a  large  amount  of  text  set  this  filter  to  TRUE.  Text  widgets  can  very  effi 
ciently  redraw  only  the  needed  parts  of  the  window  because  each  character  is  in  a  fixed  loca 
tion.  (Characters  are  in  fixed  locations  in  the  Text  widget  because  it  uses  fixed-width 
fonts — this  is  not  applicable  to  widgets  that  display  proportional  fonts.) 

8.6.3   Input  Sensitivity 

There  are  times  when  some  widgets  should  be  insensitive  to  events  in  which  they  are  usually 
interested.  For  example,  a  Command  widget  should  be  insensitive  when  the  command  that  it 
executes  is  invalid  because  a  pop-up  widget  is  in  control. 

Widget  sensitivity  is  inherited.  For  example,  if  a  parent  widget  is  insensitive,  then  its  chil 
dren  are  too.  In  other  words,  an  entire  box  full  of  widgets  can  be  set  insensitive  by  simply 
setting  the  box  widget  insensitive.  Note,  however,  that  this  process  can  be  a  little  slow 
because  all  the  widgets  in  the  box  that  honor  sensitivity  will  redraw  themselves  dimmed  or 
grayed.  A  widget  is  made  insensitive  from  an  application  by  calling  xtSetSensitive 
with  the  sensitive  argument  set  to  FALSE,  or  using  XtSetValues  on  the  Xt- 
Nsensitive  resource  (XtSetSensitive  is  slightly  faster). 

Any  widget  that  may  need  to  be  disabled  for  a  time  by  the  application  should  change  its  visi 
ble  appearance  when  insensitive. 

The  widget  that  has  one  of  the  xt Callback*  standard  pop-up  callback  functions  regis 
tered  on  its  callback  list  will  be  set  insensitive  when  the  callback  is  triggered.  If  the  xt- 
CallbackPopdown  callback  function  is  registered  on  this  widget  it  will  be  set  sensitive 
again  when  this  callback  is  invoked. 
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Resource  Management 
and  Type  Conversion 


This  chapter  is  a  more  thorough  discussion  of  how  resources  work  and  how 
they  should  be  used.  This  chapter  describes  in  detail  the  resource  file  format 
and  the  rules  that  govern  the  precedence  of  resource  settings.  It  also 
describes  how  to  add  your  own  type  converter  so  that  you  can  have  applica 
tion  or  widget-specific  data  set  through  resources.  Finally,  it  describes 
subresources  and  how  to  use  them. 
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Resource  Management 
and  Type  Conversion 


This  chapter  provides  a  thorough  discussion  of  how  resources  work  and  how  they  should  be 
used.  First,  we  describe  how  to  define  resources,  the  complete  syntax  of  resource  files,  and 
the  rules  that  describe  the  precedence  of  one  resource  setting  over  another.  For  the  sake  of 
completeness,  and  to  make  sure  that  the  ideas  are  presented  in  context,  there  is  some  repeti 
tion  of  material  that  has  been  presented  earlier. 

Next,  the  chapter  describes  the  resource  conversions  performed  automatically  by  Xt.  As  you 
may  recall  from  the  discussion  in  Chapter  2,  Introduction  to  the  X  Toolkit,  a  value  converter 
is  invoked  by  Xt  to  convert  a  resource  from  the  string  form  specified  in  resource  files  to  the 
representation  type  actually  used  in  the  application  or  widget  For  the  representation  types 
understood  by  Xt,  simply  listing  the  representation  symbol  (a  constant  beginning  with  xtR) 
in  the  resource  list  is  enough  to  make  Xt  automatically  perform  the  conversion.  But  if  you 
create  a  representation  type  unknown  to  Xt,  you  need  to  write  a  type  converter  routine  and 
register  it  with  Xt  before  the  automatic  conversion  can  take  place.  We  discuss  both  the  stan 
dard  converters  and  how  to  write  a  new  one. 

Finally,  the  chapter  describes  a  mechanism  Xt  provides  whereby  widgets  or  applications  may 
have  subparts  with  separate  sets  of  resources.  Special  routines  are  provided  for  setting  and 
getting  these  resources.  This  feature  is  rarely  used.  However,  the  R3  Athena  Text  widget 
uses  subparts.  It  has  replaceable  units  that  provide  the  source  or  sink  for  text  data.  This 
allows  the  same  central  code  to  edit  a  disk  file  or  a  string. 


9.1   Review  of  Resource  Fundamentals 

As  we've  previously  discussed,  widgets  and  applications  can  declare  some  or  all  of  their 
variables  as  resources.  Not  every  variable  need  be  a  resource,  only  those  for  which  values 
need  to  be  supplied  by  the  user  (or  for  a  widget,  also  by  the  application  programmer)  through 
the  Resource  Manager.  Both  applications  and  widgets  may  use  nonresource  variables  for 
internal  bookkeeping,  or  for  storing  values  calculated  or  otherwise  derived  from  resources. 

Resources  are  defined  using  an  Xt  Re  source  structure,  which  is  declared  as  follows: 
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typedef  struct  { 

String  resource_name;     /*  specify  using  XtN  symbol  */ 

String  resource_class;    /*  specify  using  XtC  symbol  */ 

String  resource_type;     /*  actual  data  type  of  variable  */ 

Cardinal  resource_size;   /*  specify  using  sizeof ()  */ 

Cardinal  resource_of f set;/*  specify  using  XtOffset ()  */ 

String  default_type;      /*  will  be  convrted  to  resrce_type  */ 

caddr_t  default_address;  /*  address  of  default  value  */ 

}  XtResource,  *XtResourceList; 

For  example,  Example  9-1  shows  two  of  the  resources  defined  by  the  Athena  Label  widget 

Example  9-1.  Two  resources  defined  by  the  Athena  Label  widget 

static  XtResource  resources []  =  { 

XtNforeground,   /*  Resource  name  is  foreground  */ 

XtCForeground,   /*  Resource  class  is  Foreground  */ 

XtRPixel,        /*  Resource  type  is  Pixel  */ 

sizeof (Pixel) ,   /*  allocate  enough  space  to  hold  a  Pixel  value  */ 

XtOffset (LabelWidget,  label . foreground) , /*where  in  instnce  strct*/ 

XtRString,       /*Default  val  is  a  String  (will  need  conversion) */ 

XtDefaultForeground   /*  Default  address  */ 


XtN label, 
XtCLabel, 

XtRString, 

sizeof (String)  , 

XtOffset (LabelWidget,  label . label) , 

XtRString, 

NULL 


The  fields  in  the  XtResource  structure  are  used  as  follows: 

•  The  resource  name  is  usually  similar  to  the  name  of  the  variable  being  set  by  the 
resource;  by  convention,  it  begins  with  a  lower-case  letter,  and  no  underscores  are  used  to 
separate  multiple  words.  Instead,  the  initial  character  of  subsequent  words  is  given  in 
upper  case.  For  example,  the  resource  name  for  a  variable  named  border_width 
would  be  backgroundPixel,  and  the  defined  constant  used  to  refer  to  this  name 
would  be  XtNborderWidth. 

As  described  previously,  the  name,  class,  and  representation  type  of  resources  are  speci 
fied  in  the  resource  list  (and  elsewhere  in  Xt  code,  but  not  in  user  database  files)  using 
symbolic  constants  defined  in  <Xll/StringDefs.h>,  and  consist  of  the  actual  name,  class, 
or  type  preceded  by  the  characters  XtN,  XtC,  or  xtR,  respectively.  Use  of  these  con 
stants  provides  compile-time  checking  of  resource  names,  classes,  and  types.  Without  the 
constants,  a  misspelling  would  not  be  noticed  by  the  compiler,  since  resource  names, 
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classes,  and  representation  types  are  simply  strings.  The  misspelling  would  be  considered 
a  real  resource  at  run  time.  Nothing  would  happen  if  it  were  set  from  the  application, 
because  no  widget  would  actually  use  it  If,  on  the  other  hand,  the  misspelling  were  in 
the  widget  resource  list,  the  application's  setting  of  the  intended  resource  would  have  no 
effect. 

Newly-defined  resources  may  use  a  name,  class,  or  type  constant  defined  in  <XlllString- 
Defs.h>,  if  an  appropriate  one  exists.  Otherwise,  the  constant  is  defined  in  the  widget's 
public  header  file,  or  for  application  resources,  in  the  application  itself,  or  in  the  applica 
tion  header  file,  if  any.) 

For  many  resources,  the  class  name  is  simply  the  same  as  the  resource  name,  except  that 
the  XtC  prefix  is  used,  and,  by  convention,  the  first  letter  of  the  name  is  capitalized.  For 
example,  the  class  name  constant  for  the  xtNbackgroundPixel  resource  is  xt- 
CBackgroundPixel.  However,  when  appropriate,  a  single  class  can  be  used  for  a 
group  of  related  resources.  This  allows  a  single  setting  in  the  resource  database  to  control 
the  value  of  multiple  resources. 

For  example,  a  widget  can  have  several  elements  that  use  pixel  values  (i.e.,  colors)  as 
resource  settings:  background,  foreground,  border,  block  cursor,  pointer  cursor,  and  so 
on.  Typically,  the  background  defaults  to  white  and  everything  else  to  black.  If  the 
background  resource  has  a  class  of  Background,  and  all  the  other  pixel  resources  a 
class  of  Foreground,  then  a  resource  file  needs  only  two  lines  to  change  all  back 
ground  pixels  to  offwhite  and  all  foreground  pixels  to  darkblue: 


*Background: 
*Foreground: 


offwhite 
darkblue 


The  representation  type  of  the  resource  is  specified  by  the  resource_type  field  of  the 
resource  list,  using  a  symbolic  constant  prefixed  by  xtR.  Table  9-1  lists  the  correspon 
dence  between  the  xtR  symbols  defined  by  Xt,  and  actual  C  data  types  or  X  data  types 
and  structures. 

Table  9-1.  Resource  Type  Strings 


Resource  Type 


XtRAcceleratorTable 

XtRBoolean 

XtRBool 

XtRCallback 

XtRColor 

XtRCursor 

XtRDimension 

XtRDisplay 

XtRFile 

XtRFloat 

XtRFont 

XtRFontStruct 

XtRFunction 


Datatype 


Xt Accelerators 

Boolean 

Bool 

XtCallbackList 

XColor 

Cursor 

Dimension 

Display* 

FILE* 

float 

Font 

XFontStruct  * 

(*)  () 
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Table  9-1.  Resource  Type  Strings  (continued) 


Resource  Type 


Datatype 


XtRInt 

XtRPixel 

XtRPixmap 

XtRPointer 

XtRPosition 

XtRShort 

XtRString 

XtRTranslationTable 

XtRUnsignedChar 

XtRWidget 

XtRWindow 


int 

Pixel 

Pixmap 

caddr_t 

Position 

short 

char* 

XtTranslations 

unsigned  char 

Widget 

Window 


As  we'll  discuss  in  detail  in  Section  9.3,  Xt  automatically  converts  values  in  the  resource 
database  (which  usually  have  the  type  XtRString,  since  resource  files  are  made  up 
entirely  of  strings)  into  the  target  type  defined  by  resource_type. 

The  resource_size  field  is  the  size  of  the  resource's  actual  representation  in  bytes; 
it  is  normally  specified  as  sizeof  ( type)  (where  type  is  the  C-language  type  of  the 
resource)  so  that  the  compiler  fills  in  the  value. 

The  resource_of  f  set  field  is  the  offset  in  bytes  of  the  field  within  the  widget 
instance  structure  or  application  data  structure.  The  xtOf  f  set  macro  is  normally  used 
to  obtain  this  value.  This  macro  takes  as  arguments  a  pointer  to  the  data  structure,  and 
the  name  of  the  structure  field  to  be  set  by  the  resource. 

If  no  value  is  found  in  the  resource  database,  the  value  pointed  to  by  the 
def  ault_address  field  will  be  used  instead.  The  type  of  this  default  value  is  given 
by  the  default_type  field.  If  the  default_type  is  different  from  the 
resource_type,  a  conversion  will  be  performed  automatically  in  this  case  as  well. 

There  are  two  special  resource  types  that  can  be  used  only  in  the  def  ault_type. 
xtRimmediate  means  that  the  value  in  the  def  ault_address  field  is  to  be  used 
as  the  actual  resource  value,  rather  than  as  a  pointer  to  it  xtRCallProc  is  a  pointer  to 
a  function  that  will  supply  the  default  value  at  run  time.  We'll  demonstrate  the  use  of 
these  values  in  Section  9.3.3. 
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9.2  How  the  Resource  Database  Works 

Xt's  resource  handling  is  based  on  the  resource  manager  built  into  Xlib,  but  Xt  adds  a  great 
deal.  While  using  the  resource  manager  from  Xlib  is  cumbersome,  from  Xt  it  is  easy:  to  use 
resources  in  existing  widgets,  all  you  have  to  do  is  write  the  application-defaults  file. 

Xt's  handling  of  resources  occurs  in  two  stages: 

1.  When  the  application  starts  up,  with  a  call  to  Xtlnitialize,  xtApplnitialize, 
orxtToolkitlnitialize.Xt  reads  the  application-defaults  file,  along  with  several 
other  resource  files,  command  line  options,  and  the  RESOURCE_MANAGER  property 
stored  in  the  server  by  the  user  with  xrdb.  (Any,  all,  or  none  of  these  may  contain  data.) 
It  merges  all  these  sources  of  data  into  one  internal  database  that  is  used  when  each 
widget  is  created. 

2.  Whenever  you  create  a  widget,  the  call  to  xtCreateWidget  or  xtCreate- 
Managedwidget  reads  the  resource  database  and  automatically  sets  widget  resources 
to  the  values  in  the  database.   In  order  to  explain  this  stage  more  clearly,  we  further 
divide  it  into  two  separate  steps  in  the  sections  that  follow.  First,  Xt  compares  the  set 
tings  in  the  database  to  the  widget's  class  and  instance  hierarchy,  to  find  which  settings 
apply  to  the  widget  being  created.  Second,  Xt  decides  which  of  the  (possibly  conflicting) 
settings  that  apply  to  that  widget  should  actually  be  used. 

If  the  value  of  a  resource  is  hardcoded  into  an  ArgList  passed  as  an  argument  to  xt- 
CreateWidget,  XtCreateManagedWidget  or  xtSetValues,  the  hardcoded 
value  overrides  the  value  looked  up  from  the  resource  database. 

To  retrieve  the  value  of  application  resources  from  the  database,  an  application  must  make  an 
explicit  call  to  XtGetApplicationResources,  as  described  in  Section  3.5.3. 

9.2.1    Form  of  Resource  Specifications 

As  discussed  in  Chapter  2,  each  entry  in  the  merged  database  (and  in  the  source  databases)  is 
a  resource  specification/value  pair.  For  application  resources,  the  specification  is  the  applica 
tion  name  followed  by  a  period  and  the  resource  name.  The  value  to  which  the  resource  is  to 
be  set  follows,  after  a  colon  and  optional  white  space.*  For  example: 

xterm.scrollBar :      on 
An  asterisk  can  be  used  as  a  "wildcard"  in  place  of  the  application  name.  For  example: 

*scrollBar:   on 

would  set  a  resource  named  scrollBar  to  "on"  in  any  application  that  recognized  a 
resource  of  that  name. 


*Note  the  distinction  between  what  we  are  calling  the  resource  specification  (the  fully  qualified  name  of  the  resource, 
up  to  the  colon),  and  the  value  (the  actual  value  to  which  the  resource  is  to  be  set).  We  refer  to  both  the  specification 
and  the  value  together  as  a  resource  setting. 
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For  widget  resources,  the  specification  leading  up  to  the  resource  name  may  contain  a  widget 
instance  or  class  hierarchy  (or  a  mixed  instance/class  hierarchy).  Some  examples  are  shown 
below. 

specification  value 

I  I 

xbitmap .  box .  quit .  label :  Quit       fully-specified  instance  hierarchy 

XBitmap  .Box.  Command.  Foreground:  blue       fully-specified  class  hierarchy 

XBitmap.  Box.  quit .  foreground:  blue       mixed  class  and  instance  hierarchy 

An  instance  hierarchy  describes  the  instance  names  of  the  widget's  ancestors.  A  class  hierar 
chy  describes  the  class  names  of  the  widget's  ancestors.  This  portion  of  the  resource  specifi 
cation  may  consist  of  a  mixture  of  instance  names  and  class  names  (each  of  which  describes 
one  generation  in  the  widget's  hierarchy),  separated  by  periods  or  asterisks. 

•  A  period  (.)  is  referred  to  as  a  tight  binding. 

•  An  asterisk  (*)  is  referred  to  as  a  loose  binding. 

A  tight  binding  means  that  the  left  component  must  be  the  parent  of  the  right  component  in 
the  instance  hierarchy.  A  loose  binding  means  that  the  left  component  must  only  be  an 
ancestor  of  the  right  component;  there  can  be  any  number  of  levels  in  the  hierarchy  between 
the  two. 

Loose  bindings  are  preferable  because  they  stand  a  better  chance  of  working  when  the 
instance  hierarchy  changes.  Tight  bindings  are  rarely  necessary  at  every  position  in  the 
resource  specification,  since  widget  names  are  usually  unique  and  single  widgets  can  be  iden 
tified  by  name.  Furthermore,  it  takes  more  text  to  specify  the  complete  instance  hierarchy  for 
every  widget  to  be  set 

Using  loose  bindings,  the  instance,  class,  or  instance/class  hierarchy  may  be  abbreviated  to 
the  point  where  specifying  the  hierarchy  as  a  single  asterisk  would  indicate  that  any  instance 
or  class  hierarchy  (any  widget  in  the  application)  will  match. 

The  resource  name  must  be  the  string  that  appears  in  the  resource  name  or  resource  class  field 
in  a  resource  list.  This  is  the  value  of  the  xtN  or  xtC  symbolic  constant  used  in  that  field  of 
the  resource  list. 

Any  entry  that  is  not  a  resource  specification/value  pair  or  does  not  match  any  resource  for 
any  widget  in  the  application  or  any  application  resource  is  quietly  ignored  (no  warning  mes 
sage  is  printed).  This  means  that  a  slight  error  in  the  resource  specification  of  an  entry  will 
cause  that  entry  to  be  quietly  and  completely  ignored.  It  is  often  difficult  to  detect  such 
errors. 

Lines  beginning  with  an  exclamation  point  (!)  are  treated  as  comments.  Many  people  use  # 
instead,  which  is  currently  supported  in  MIT's  sample  implementation  of  Xt,  but  is  not  man 
dated  in  the  Xt  specification  and  therefore  may  be  eliminated  in  future  sample  implementa 
tions  from  MIT  or  in  a  vendor's  implementation.  You  are  advised  to  use  the  exclamation 
point.  (Even  in  the  MIT  implementation,  #  elicits  warning  messages  from  xrdb.) 
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9.2.2   Merging  of  Resource  Files 

xt initialize,  among  others,  constructs  the  resource  database  by  consulting  the  follow 
ing  sources  of  resource  settings,  in  this  order: 

1.  A  file  in  the  directory  lusrlliblXlllapp-defaults  on  the  machine  running  the  client.  The 
name  of  this  file  is  the  application  class  (specified  in  the  xt  initialize  call),  usually 
the  same  as  the  application  name  except  with  the  first  letter  capitalized.  If  the  application 
name  begins  with  x,  then  the  first  two  letters  are  capitalized.  (This  latter  convention  is 
not  always  followed.)  This  is  the  application-defaults  file,  intended  to  be  written  by  the 
application  developer.  The  installation  procedure  for  the  application  should  install  this 
file  in  the  correct  directory. 

2.  Files  with  the  same  name  as  the  file  in  lusrlliblXlllapp-defaults,  except  in  the  directory 
named  by  the  shell  environment  variable  XAPPLRESDIR  on  the  system  running  the  client, 
or  if  the  variable  is  not  set,  in  the  user's  home  directory.  This  file  is  intended  to  be  the 
user's,  or  possibly  the  site  administrator's,  customization  for  the  particular  application. 
The  application  developer  can  also  set  XAPPLRESDIR  so  that  resource  files  for  an  appli 
cation  can  be  in  the  same  directory  as  the  application.  (This  is  particularly  useful  when 
debugging  the  application-defaults  file.)  Note  that  the  value  of  this  variable  must  end 
with  a  slash  (/).* 

3.  Resources  loaded  into  the  RESOURCE_MANAGER  property  of  the  root  window  with  xrdb. 
Unlike  any  of  the  resource  files,  these  resources  are  accessible  regardless  of  the  machine 
on  which  the  client  is  running.  Therefore,  xrdb  saves  you  from  having  to  keep  track  of 
resource  files  on  several  different  systems.  Typically,  the  user  arranges  to  have  xrdb  run 
automatically  from  jcinitrc  or  its  equivalent  under  xdm,  the  display  manager.  This  is 
intended  to  be  the  method  whereby  the  user  specifies  server-wide  resources  (to  apply  to 
all  clients  no  matter  which  system  they  are  running  on). 

If  the  RESOURCE_MANAGER  property  is  not  set,  the  resource  manager  looks  for  an  Xde- 
faults  file  in  the  user's  home  directory.  Support  for  Xdefaults  is  mostly  for  compatibility 
with  earlier  releases  of  X.  (See  Volume  Three,  X  Window  System  User's  Guide,  for  more 
information  on  using  xrdb.) 

4.  Next,  the  contents  of  any  file  (on  the  system  running  the  client)  specified  by  the  shell 
environment  variable  XENVIRONMENT  will  be  loaded.  The  difference  between  this  and 
APPLRESDIR  above  is  that  this  is  a  complete  path  name  including  the  file  name. 

If  this  variable  is  not  defined,  the  resource  manager  looks  for  a  file  named  Xdefaults- 
hostname  (with  a  hyphen)  in  the  user's  home  directory,  where  hostname  is  the  name  of 
the  host  where  the  client  is  running.  (On  systems  with  a  network  file  system,  the  home 
directory  may  be  on  a  system  different  from  the  one  where  the  application  is  running,  the 
one  where  the  server  is  running,  or  both.) 

*If  you  break  the  conventions  by  giving  your  program  binary  a  capitalized  name,  or  by  giving  your  application-de 
faults  file  a  lower-case  name,  it  is  possible  to  have  the  binary  accidentally  interpreted  as  an  application  default  file. 
The  entire  binary  will  be  searched  for  resource  lines!  Since  the  binary  is  so  large,  your  application  will  start  up  very 
slowly.  No  error  will  be  reported  because  the  resource  manager  quietly  ignores  entries  it  doesn't  understand. 
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5.  Any  values  specified  on  the  command  line  with  the  -xrm  option  will  be  loaded  for  that 
instance  of  the  program. 

6.  If  the  application  has  defined  any  command-line  options  by  passing  an  options  table  to 
xtlnitialize,  values  from  the  command  line  will  override  those  specified  by  any 
other  resource  settings. 

The  order  in  which  these  various  sources  are  loaded,  as  shown  in  the  list  above,  is  the  reverse 
order  of  their  priority.  That  is,  those  that  are  loaded  first  will  be  overridden  by  those  loaded 
later  if  an  identical  specification  is  found. 

If  a  widget  is  created  with  a  resource  value  hardcoded  in  an  ArgList,  that  value  takes  pre 
cedence  over  the  value  for  that  resource  in  the  resource  database.  If  a  widget  is  created  and 
no  setting  exists  in  the  database  for  a  particular  resource,  the  value  pointed  to  by  the 
def  ault_address  field  of  the  resource  list  is  used.  This  is  also  true  for  application 
resources  and  subresources. 

In  practice,  few  users  use  more  than  one  or  two  of  these  sources  of  resource  settings. 

9.2.3    Resource  Matching  Algorithm 

When  a  widget  is  created,  its  expanded  instance  hierarchy  and  class  hierarchy  together  with 
its  resource  names  and  classes  are  compared  to  each  entry  in  the  merged  resource  database. 
To  demonstrate  how  matches  are  made,  we'll  look  at  a  sample  widget  hierarchy  and  follow 
the  process  of  finding  the  value  for  one  resource  of  one  widget  from  the  merged  resource 
database.  Figure  9-1  shows  the  widget  instance  hierarchy  for  the  quit  widget  in  the  xbox 
application  shown  in  Chapter  3,  More  Widget  Programming  Techniques.  The  figure  also 
shows  the  corresponding  fully  specified  instance  and  class  names  for  the  quit  widget  This 
section  describes  how  this  widget's  resources  are  set  by  the  resource  manager. 

We  know  that  quit  is  a  Command  class  widget  and  therefore  that  Xt  will  be  searching  the 
resource  database  for  each  resource  in  Command's  resource  list  (and  the  resources  in  its 
superclasses'  resource  lists).  It  will  search  for  one  resource  at  a  time.  To  demonstrate  the 
conflicts  that  can  occur,  we'll  use  the  Core  resource  xtNbackground,  which  is  common 
to  all  widgets.  It  will  appear  in  the  resource  database  as  background. 

The  matching  process  can  be  thought  of  as  a  process  of  elimination.  Let's  assume  the 
merged  resource  database  is  as  shown  in  Example  9-2. 


*The  actual  algorithm  used  by  Xt  differs  slightly  from  that  described  here,  because  there  are  shortcuts  that  the  re 
source  manager  takes  that  are  hard  to  follow  even  if  you  have  the  source  code.  However,  the  algorithm  described 
here  gives  the  same  result,  with  more  clarity. 
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instance  name:      xbox 
class  name:     XBOX 


instance  name:     box 
class  name:      BOX 


instance  name:      quit 
class  name:      Command 


Fully-specified  instance  name: 
Fully-specified  class  name: 


xbox . box . quit 
XBox . Box . Command 


Figure  9-1.  The  quit  widget  in  a  sample  widget  hierarchy 

Example  9-2.  A  sample  merged  resource  database 

*box.  background:  blue  (entry  1) 

*background:  red  (entry  2) 

*quit  .background:  green  (entry  3) 

*quit. label:  Quit  (entry  4) 

*Command. background:  yellow  (entry  5) 

*  Box.  Command,  background:  violet  (entry  6) 

*box*background:  pink  (entry?) 

xbox. background:  orange  (entry  8) 

Only  resource  database  entries  that  specify  background  as  the  last  element  before  the 
colon  are  possible  matches.  That  eliminates  entry  4.  The  fully  specified  instance  and  class 
hierarchies  are  then  compared  with  each  possible  match,  beginning  with  the  first  component 
in  each  hierarchy. 

1.   Every  entry  beginning  with  the  asterisk  wildcard  binding  (*)  as  well  as  the  one  beginning 
with  xbox,  matches  xbox,  the  first  component  of  the  fully  specified  instance  name.  All 
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those  beginning  with  *  also  match  the  first  component  of  the  fully  specified  class  name, 
XBox.  Since  entry  8  actually  contains  the  string  xbox,  the  xbox  component  is  removed 
for  comparison  at  the  next  level.  Entry  8  now  begins  with  .  background. 

2.  The  first  component  of  each  resource  specification  (after  removal  of  previously  matched 
components)  is  now  compared  to  the  second  element  in  the  widget's  class  and  instance 
hierarchies.  This  should  be  either  box  or  Box.    All  the  entries  that  begin  with  *  still 
match,  because  *  matches  any  number  of  levels  in  the  hierarchy.  However,  there  is  no 
second  element  in  entry  8,  once  the  resource  name  background  is  removed.  There 
fore,  entry  8  is  eliminated.  Also,  since  entries  1,6,  and  7  actually  contain  the  strings  box 
or  Box,  the  leading  asterisk  and  the  strings  box  and  Box  are  removed  before  compari 
son  of  the  next  level.  Example  9-3  shows  the  resource  database  as  it  would  appear  after 
the  components  and  entries  eliminated  so  far. 

Example  9-3.  Sample  resource  database  with  eliminated  entries  and  components 

.background:  blue  (entry  1) 

^background:  red  (entry  2) 

*quit  .background:  green  (entry  3) 

*Command.  background:  yellow  (entry  5) 

.  Command. background:  violet  (entry  6) 

*background:  pink  (entry?) 

Note  that  entries  2  and  7  are  now  duplicates  except  for  the  resource  value.  The  resource 
manager  actually  eliminates  one  of  these  entries  based  upon  the  levels  at  which  each 
entry  matched,  whether  the  instance  name  or  class  name  matched,  whether  a  tight  or 
loose  binding  was  used,  and  which  had  more  elements  specified.  These  are  the  prece 
dence  rules  to  be  described  in  the  next  section.  In  order  to  keep  the  example  clearer, 
we'll  pretend  that  the  resource  manager  keeps  the  information  necessary  to  apply  all  the 
precedence  rules,  and  keeps  all  the  entries,  until  the  end. 

3.  Now  the  contents  of  the  resource  database  are  compared  to  the  third  component  in  the 
widget's  instance  and  class  hierarchies,  quit  and  Command.  As  usual,  anything  begin 
ning  with  an  asterisk  or  anything  beginning  with  a  period  (.)  followed  by  either  the 
expected  class  or  instance  name  is  a  match.  This  matches  all  but  entry  1,  which  is  elim 
inated. 

Before  going  on  to  the  next  comparison,  any  components  that  matched  specifically  (a  .  or 
*  followed  by  either  string)  are  removed,  which  results  in  the  resource  database  shown  in 
Example  9-4. 

Example  9-4.  Resource  database  after  final  elimination  of  entries  and  components 

*background:  red  (entry  2) 

.background:  green  (entryS) 

.background:  yellow  (entry  5) 

.background:  violet  (entry  6) 

*background:  pink  (entry?) 

Now  you  see  that  we  are  left  with  only  the  resource  names  and  tight  or  loose  bindings.  The 
matching  process  is  finished,  and  the  precedence  analysis  begins.  The  next  section  describes 
the  precedence  rules  and  then  finishes  this  example  to  determine  the  priority  of  the  finalist 
entries. 
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9.2.4   Resource  Precedence  Rules 

Because  of  the  way  merging  works,  no  two  resource  specifications  in  the  merged  resource 
database  will  be  alike.  (Remember  that  we  are  using  the  term  specification  for  the  part  of  the 
resource  setting  up  to  and  including  the  colon.)  For  example,  the  merged  database  could 
never  contain  both  of  the  following: 

XBitmap*box*background:  green 
XBitmap*box*background:  red 

because  the  merging  process  would  remove  the  setting  that  appeared  earlier  in  the  list  of 
database  sources. 

However,  the  database  could  contain  two  or  more  resource  settings  that  apply  to  the  same 
resource  of  the  same  widget,  because  of  differences  in  the  widget  class  or  instance  hierarchy 
or  the  bindings.  For  example,  the  database  could  contain: 

XBitmap*box*background:  green 
XBitmap*quit .background:  red 

If  the  quit  button  is  a  child  of  box,  both  settings  apply  to  the  quit  button's  background. 

The  resource  manager  provides  a  set  of  rules  that  govern  which  setting  takes  precedence  in 
cases  where  there  are  two  settings  for  the  same  resource  of  the  same  widget.  Here  are  the 
four  rules: 

1.  A  specification  that  includes  higher  components  in  the  instance  or  class  hierarchy  takes 
precedence  over  one  that  includes  only  lower  ones. 

*topLevel*quit  .background:  takes  precedence  over 

* box* quit .background: 

2.  Instance  names  take  precedence  over  class  names  at  the  same  level  in  the  hierarchy. 

*guit  .background:  takes  precedence  over 

*Command . background : 

3.  Tight  bindings  take  precedence  over  loose  bindings  at  the  same  level  in  the  hierarchy. 

*box .  background :  takes  precedence  over 

*box*background : 

4.  A  name  or  class  that  is  explicitly  stated  takes  precedence  over  one  that  is  omitted. 

*box*quit  .background:  takes  precedence  over 

*box*background : 

To  understand  the  application  of  these  rules,  let's  return  to  our  extended  example.  In  the 
course  of  developing  that  example,  we  eliminated  information  about  the  level  at  which  com 
ponents  occurred.  However,  the  actual  process  of  matching  applies  the  precedence  rules  at 
each  step.  As  a  result,  let's  start  again  with  the  original  appearance  of  the  entries  that  pass 
the  matching  test.  The  remaining  five  as  they  appeared  originally  are  shown  in  Example  9-5. 
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Example  9-5.  Resource  database  finalists  in  original  form 

background:  red  (entry  2) 

*quit  .background:  green  (entry  3) 

^Command,  background:  yellow  (entry  5) 

*Box. Command. background:  violet  (entry  6) 

*box*background:  pink  (entry?) 

From  here  on,  we  will  determine  not  only  which  one  of  these  five  will  take  effect,  but  the 
actual  precedence  of  the  five.  In  other  words,  once  the  one  with  highest  precedence  is  deter 
mined,  we'll  see  which  would  take  effect  if  that  one  was  commented  out,  and  so  on. 

The  precedence  rules  are  applied  in  order  to  determine  the  order  of  the  finalist  entries. 

1.  Rule  1  specifies  that  a  specification  that  contains  higher  components  in  the  instance  or 
class  hierarchy  takes  precedence  over  one  that  contains  only  lower  ones.  The  highest 
components  that  appear  in  our  example  are  box  and  Box  in  entries  6  and  7.  Therefore, 
these  two  have  higher  priority  than  any  others. 

2.  To  choose  between  these  two,  we  continue  to  Rule  2.  Instance  names  (box)  take  prece 
dence  over  class  names  (Box).  Therefore,  entry  7  has  the  highest  precedence,  followed 
by  entry  6.  Note  that  the  precedence  comparison  of  two  finalists  proceeds  in  the  same 
manner  as  the  original  matching — from  left  to  right  in  the  entry,  one  component  at  a 
time. 

3.  To  determine  the  precedence  of  the  remaining  three  entries,  2,  3,  and  5,  we  begin  again 
with  Rule  1.  However,  Rule  1  does  not  apply  because  no  two  entries  here  specify  differ 
ent  levels  in  the  hierarchy.  Entries  3  and  5  contain  the  quit  level  and  entry  2  nothing 
(an  asterisk  does  not  count  for  Rule  1  because  it  is  not  a  specified  level — it  is  any  level). 
Rule  2  specifies  that  the  instance  name  quit  takes  precedence  over  the  class  name 
Command,  and  therefore  entry  3  has  higher  priority  than  entry  5.  Rule  3  does  not  apply, 
because  no  two  entries  are  identical  except  for  binding.  Because  of  Rule  4  we  know  that 
both  entries  3  and  5  are  higher  priority  than  entry  2,  because  3  and  5  state  a  name  or  class 
that  is  omitted  in  2. 

Therefore,  the  final  precedence  is  as  shown  here: 

1.  *box*background:  pink  (entry?) 

2.  *Box.  Command,  background:  violet  (entry  6) 

3.  *quit  .background:  green  (entry  3) 

4.  *Command.  background:  yellow  (entry  5) 

5.  *background:  red  (entry  2) 

Rules  2,  3,  and  4  are  fairly  easy  to  understand  and  apply,  but  many  people  forget  or  are  con 
fused  by  Rule  1.  People  get  used  to  the  fact  that  they  can  set  the  resources  of  all  the  children 
of  box  with  something  like  entry  7,  but  then  are  shocked  to  find  that  nothing  happens  when 
they  attempt  to  override  entry  7  with  entry  3 — entry  3  seems  more  specific  to  them.  Even  the 
following  entry  (using  a  class  name)  takes  precedence  over  entry  3  because  the  rule  about 
being  higher  in  the  widget  hierarchy  carries  more  weight  than  the  rule  that  instance  names 
take  precedence  over  class  names: 

*Box*background:  pink     (entry?) 

The  moral  of  this  story  is  that  there  is  only  one  way  to  be  sure  you  are  setting  a  particular 
resource  of  a  particular  widget  in  such  a  way  as  to  override  all  other  settings  that  might  apply 
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to  that  resource:  you  must  specify  all  the  levels  in  the  instance  hierarchy,  with  tight  bindings 
between  each  component.  (But  of  course,  this  will  not  work  when  another  resource  file  that 
is  merged  later  also  specifies  the  same  resource  and  all  components  of  the  same  widget  with 
the  instance  hierarchy  separated  by  tight  bindings.)  Since  there  are  no  messages  telling  you 
which  resource  specifications  are  actually  being  used,  you  can  be  tricked  into  thinking  that 
you  have  set  resources  that  you  actually  haven't.  Using  only  tight  bindings  in  the  applica 
tion-defaults  file,  while  more  trouble  initially,  is  probably  wise  in  the  long  run. 

Figure  9-2  illustrates  the  entire  process  of  resource  matching. 


9.3  Type  Conversion 

You  already  know  that  Xt  is  capable  of  converting  resource  values  from  the  string  representa 
tion  specified  in  resource  files  to  the  actual  type  required  in  code.  In  fact,  Xt  does  so  auto 
matically  if  the  resource  list  is  properly  written.  This  section  describes  this  process  in  more 
detail,  and  tells  you  how  to  create  converters  for  converting  your  own  data  types. 

9.3.1    Conversions  from  XtRString 

The  primary  purpose  of  converters  is  to  allow  resource  files  to  contain  string  values  for  non- 
string  program  variables.  (They  are  also  used  internally  to  convert  default  values  that  cannot 
be  specified  easily  in  the  desired  data  type.)  Secondly,  converters  confine  the  details  of  data 
conversion  to  a  single  routine  that  is  registered  with  Xt.  This  is  a  big  benefit  because  users  of 
the  converted  types  need  not  know  the  details  of  how  the  conversion  takes  place,  or  the  inter 
nal  definition  of  the  target  type. 

Xt  provides  converters  from  XtRString  to  the  representation  types  listed  in  Table  9-2. 
These  are  the  representation  types  that  you  can  use  as  target  types  in  resource  lists  in  applica 
tions  or  widgets,  without  having  to  register  them  or  do  anything  else,  if  you  want  the  user  to 
be  able  to  specify  the  resource  in  a  resource  file. 
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Select  entries  from  resource  data  base  whose  last 
element  is  the  background  resource  being  set. 


>/ 

Determine  fully-specified  class  and  instance  name  for 
widget. 


4- 

Compare  first  element  of  each  entry  to  first  element  of  full 
class  and  instance  name,  xbox  and  xBox . 


xclock . background : 

*Box . Command . background : 

*box*background: 

xbO3C .  background : 


yellow 

violet 

pink 

orange 


Eliminate  entries  that  don't  match  and  eliminate 
matching  elements  that  specify  the  instance  or  class 
name,  xbox  is  removed. 

*Box .Command. background:       violet 
*box*background:  pink 

.background:  orange 


Loop  back  to    LzJ  ,  comparing  first  element  of  each  entry 
(after  removal  of  matching  elements)  to  second  element  of 
full  class  and  instance  name,  box  and  BOX  . 
Repeat  using  each  level  in  full  class  or  instance  hierarchy 
until  database  consists  of  tight  or  loose  bindings  and 
resource  names  only. 


Using  original  form  of  remaining  database  entries,  apply 
precedence  rules. 


Figure  9-2.  Steps  in  matching  resource  entries  for  one  resource  of  widget  being  created 
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Table  9-2.  Built-in  Type  Converters  from  XtRString 


Target  Type 


Description  of  Converter 


XtRAcceleratorTable 


XtRBoolean 

XtRBool 
XtRCursor 
XtRDimension 
XtRDisplay 

XtRFile 

XtRFloat 

XtRFont 


XtRFontStruct 


XtRInt 
XtRPixel 


XtRPosition 

XtRShort 

XtRTranslationTable 

XtRUnsignedChar 


Compiles  a  string  accelerator  table  into  internal  accelerator 
table  format  (no  need  to  call  XtParseAccelerator- 
Table). 

Converts  strings  "true,"  "false,"  "yes,"  "no,"  "on,"  "off  to  cor 
responding  Boolean  value  (case  insensitive). 
Same  as  for  XtRBoolean. 
Given  a  standard  X  cursor  name,  returns  a  cursor  ID. 
Converts  a  width  or  height  value  to  a  Dimension. 
Given  a  display  name,  opens  the  display  and  returns  a  Dis 
play  structure. 

Given  a  filename,  opens  the  file  and  returns  the  file  descriptor. 
Converts  a  numeric  string  to  floating  point 
Given  a  font  name,  loads  the  font  (if  it  is  not  already  loaded), 
and  returns  the  font  ID.  See  Appendix  C,  Specifying  Fonts 
and  Colors,  for  more  information  on  legal  values.  The  value 
xtDef  aultFont  will  return  the  default  font  for  the  screen. 
Given  a  font  name,  loads  the  font  (if  it  is  not  already  loaded), 
and  returns  a  pointer  to  the  Font  Struct  containing  font 
metrics.  The  value  XtDef  aultFont  will  return  the  default 
font  for  the  screen. 

Converts  a  numeric  string  to  an  integer. 
Converts  a  color  name  string  (e.g.,  "red"  or  "#FFOOOO")  into 
the  pixel  value  that  will  produce  the  closest  color  possible  on 
the  hardware.  See  Appendix  C,  Specifying  Fonts  and  Colors, 
for  more  information  on  legal  values.  The  two  values  xtDe- 
faultBackground  and  XtDefaultForeground  are 
always  guaranteed  to  exist,  and  to  contrast,  on  any  server. 
Converts  an  x  or  y  value  to  a  Position. 
Converts  a  numeric  string  to  a  short  integer. 
Compiles  string  translation  table  into  internal  translation  table 
format  (no  need  to  call  XtParseTranslationTable). 
Converts  a  string  to  an  unsigned  char. 


If  there  is  no  converter  from  XtRString  to  a  particular  resource  type,  it  may  not  be  pos 
sible  to  specify  that  resource  type  in  a  resource  file.  For  example,  there  is  no  converter  for 
xtRCallback  since  it  would  be  meaningless  to  specify  a  function  in  a  resource  file.  The 
proper  way  to  set  a  callback  resource  is  with  xtAddCallback  or  a  static  callback  list 
declared  in  the  application. 

Some  converters  that  are  widely  needed,  however,  are  not  provided  by  Xt.  For  example, 
many  applications  need  a  converter  from  a  filename  (string)  to  a  pixmap  suitable  for  use  as 
an  icon  or  background  pximap.  Fortunately,  the  Xmu  library  contains  several  commonly 
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used  converters.  Even  though  Xmu  (like  Xaw)  is  not  part  of  the  X  Consortium  standard,  it  is 
part  of  MIT's  core  distribution  and  is  available  on  most  systems. 

However,  because  the  Xmu  converters  are  not  built  into  Xt,  you  need  to  register  them  with  a 
call  to  xtAddConverter  before  using  them  in  an  application  or  widget  (We'll  describe 
the  converters  and  show  how  to  register  them  in  Section  9.3.4.) 


9.3.2   Other  Built-in  Type  Conversions 

While  the  conversions  from  xtRString  are  the  most  widely  used,  because  they  allow  a 
resource  to  be  specified  from  a  resource  file,  there  are  also  a  number  of  built-in  converters 
between  other  data  types,  for  use  internally  within  Toolkit  programs. 

Most  commonly,  these  converters  are  used  to  convert  between  the  resource_type  and 
def  ault_type  fields  of  a  resource  definition. 

Table  9-3  lists  those  converters  automatically  recognized  by  Xt. 
Table  9-3.  Other  Built-in  Converters 


From 

To 

Description  of  Converter 

XtRColor 

XtRPixel 

Converts  an  XGolor  structure  to  a  pixel  value. 

XtRPixel 

XtRColor 

Converts  a  pixel  value  to  an  XGolor  structure. 

XtRInt 

XtRBoolean 

Converts  an  int  to  a  Boolean. 

XtRBool 

Converts  an  int  to  a  Boolean. 

XtRColor 

Converts  an  int  to  an  XColor. 

XtRDimension 

Converts  an  int  to  a  Dimension. 

XtRFloat 

Converts  an  int  to  a  float. 

XtRFont 

Converts  an  int  to  a  Font. 

XtRPixel 

Converts  an  int  to  a  pixel  value. 

XtRPixmap 

Converts  an  int  to  a  Pixmap. 

XtRPosition 

Converts  an  int  to  a  Position. 

XtRShort 

Converts  an  int  to  a  short. 

XtRUnsignedChar 

Converts  an  int  to  an  unsigned  char. 

For  example,  the  Core  resource  xtNborderPixmap  has  its  default  value  set  as  shown  in 
Example  9-6. 

Example  9-6.  A  resource  definition  converting  an  int  to  a  pixmap 
static    XtResource    resources!]    =    { 


XtNborderPixmap, 

XtCPixmap, 

XtRPixmap, 
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Example  9-6.  A  resource  definition  converting  an  int  to  a  pixmap  (continued) 

sizeof (Pixmap) , 

XtOffset (WindowObj,  win_obj .border_pixmap) , 
XtRInt, 
(caddr_t)  &XtUnspecif iedPixmap 


The  specified  default  value  xtUnspec  if  iedPixmap  is  an  integer  defined  to  have  a  value 
that  does  not  equal  the  constant  CopyFromParent  or  any  valid  Pixmap  ID.  The  ini 
tialize  method  for  the  Core  widget  class  checks  for  this  value,  and  does  not  set  the 
background  window  attribute  unless  the  application  or  a  resource  file  has  set  the  Xt- 
Nborder Pixmap  resource  to  some  value  other  than  the  default. 


9.3.3   Special  Resource  Defaults  That  Do  Not  Use  Conversion 

There  are  two  special  values,  xtRlmmediate  and  xtRCallProc  that  can  be  used  only 
in  the  def  ault_type  field  of  a  resource  definition.  These  values  require  no  type  conver 
sion.  The  value  provided  in  the  def  ault_address  field  must  be  of  the  correct  type. 

The  type  XtRlmmediate  means  that  the  value  in  the  def  ault_address  field  is  the 
default  value  itself,  not  its  address. 

In  Example  9-7,  the  value  in  the  def  ault_address  field  of  the  xtNheight  resource 
definition  is  the  actual  default — in  this  case,  zero. 

Example  9-7.  A  resource  definition  using  XtRlmmediate 

static  XtResource  resources []  =  { 


XtNheight, 
XtCHeight, 
XtRD  intension, 
sizeof (Dimension) , 

XtOffset (RectObj,  rectangle .height ) , 
XtRlmmediate, 
(caddr_t)  0 
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The  type  xtRCallProc  means  that  the  value  in  the  default_address  field  is  the 
name  of  a  function.  This  function  is  of  type  xtResourceDefaultProc,  and  it  is 
expected  to  retrieve  the  desired  default  value  at  run  time.*  When  the  widget  instance  is 
created,  the  function  is  automatically  invoked  with  these  parameters:  the  widget  ID,  the 
resource  offset,  and  a  pointer  to  the  XrmValve  in  which  to  store  the  result.  The  function 
should  fill  in  the  addr  field  of  the  XrmValue  with  a  pointer  to  the  default  data  in  its  cor 
rect  type. 

In  Example  9-8,  the  value  in  the  def  ault_address  field  of  the  xtNscreen  resource 
definition  is  the  name  of  a  function  that  will  retrieve  the  screen  on  which  the  widget  is 
displayed. 

Example  9-8.  A  resource  definition  using  XtRCallProc 

static  XtResource  resources []  =  { 


XtNscreen, 

XtCScreen, 

XtRPointer, 

sizeof (int) , 

XtOf f set (WindowOb j,  win_ob j . screen) 

XtRCallProc, 

(caddr_t)  XtCopyScreen 


Example  9-9  shows  an  example  of  an  XtResourceDefaultProc. 
Example  9-9.  An  example  of  an  XtResourceDefaultProc 

/*ARGSUSED*/ 

void  XtCopyScreen (widget,  offset,  value) 

Widget  widget; 

int  offset; 

XrmValue  *value; 
{ 

value->addr  =  (caddr_t) (&widget->core .screen) ; 


*The  def  ault_address  field  in  the  resource  structure  is  declared  in  R3  as  a  caddr_t.  On  some  machine  ar 
chitectures,  this  type  may  be  too  small  to  hold  procedure  variables.  In  R4,  all  caddr_t  fields  have  been  changed  to 
type  XtPo inter,  so  that  architectures  with  large  pointers  can  redefine  this  type. 
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9.3.4    Registering  Type  Converters 


As  noted  earlier,  not  every  resource  type  symbol  defined  in  StringDefs.h  is  supported  by  a 
built-in  converter,  though  the  Xmu  library  does  provide  some  of  the  most  important  missing 
converters.  In  addition,  you  can  define  your  own  resource  types,  and  write  converter  routines 
to  convert  from  a  string  representation  in  a  resource  file  to  the  appropriate  data  type. 

Table  9-4  lists  the  converters  from  XtRString  provided  by  the  Xmu  library. 
Table  9-4.  Xmu  Converters 


From 

To 

Description  of  Converter 

XtRString 

XtRBackingStore 

The  XmuCvtStringToBackingStore  converter 

converts  the  strings  "NotUseful,"  "WhenMapped,"  and 

"Always"  (in  any  case)  into  the  corresponding  con 

stants    (in    proper    case)    for    use    in    setting    the 

backing   store  window  attribute.    (See  Volume 

One,    Xlib   Programming    Manual,    for    details    on 

backing  store.) 

XtRCursor 

The  XmuCvtStringToCursor  converter  converts 

one  of  the  standard  cursor  names  (from  <Xlllcursor- 

font.h\  a  font  name  and  glyph  index  of  the  form 

"FONT  fontname  index  [[font]  index]",  or  a  bitmap 

file  name  as  in  XtRPixmap  below,  and  converts  it  to 

anX  Cursor. 

XtRJustify 

The   XmuCvtStringToJustify   converter  con 

verts  the  strings  "right,"  "left,"  or  "center,"  in  any  case, 

to  an  enumeration  constant  suitable  for  use  by  a  justify 

resource.  This  converter  is  used  by  the  Athena  Label 

widget. 

XtROrientation 

The   XmuCvtStringToOrientation   converter 

converts  the  strings  "horizontal,"  or  "vertical,"  in  any 

case,  to  an  enumeration  constant  suitable  for  use  by  an 

orientation  resource.   This  converter  is  used  by  the 

Athena  Scroll  widget. 

XtRPixmap 

Given  a  string  representing  a  filename  in  standard  XI  1 

bitmap  file  format,  the  XmuCvtStringToPixmap 

converter  creates  a  depth-  1  pixmap  suitable  for  win 

dow  manager  icons  or  for  tiling  a  window  background 

or  border.  The  filename  may  be  an  absolute  pathname, 

or  may  be  relative  to  a  pathname  specified  in  the  glo 

bal  resource  bitmapFilePath,  class  Bitmap- 

FilePath.  If  the  resource  is  not  defined,  its  default 

value  is  the  directory  lusrlliblXl  I/bitmaps. 
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Table  9-4.  Xmu  Converters  (continued) 


From 


To 


Description  of  Converter 


XtRWidget 


XtRFunction 


XtRCallback 


The  XmuCvtStringToWidget  converter  converts 
a  widget  name  into  the  corresponding  widget  ID.  This 
is  commonly  done  to  specify  the  relative  positions  of 
the  children  of  constraint  widgets,  as  in  the  Athena 
Form  widget  resources  fromHoriz  and  from- 
Vert. 

Converts  a  function  pointer  to  a  callback  list  contain 
ing  that  function. 


Whether  defined  in  Xmu  or  in  your  own  program,  a  converter  other  than  those  built  into  Xt 
must  be  registered  with  a  call  to  xtAddConverter  before  a  resource  list  is  used  that  ref 
erences  the  converted  types.  Resource  lists  are  used  when  widgets  are  created  or  when  the 
application  calls  xtGetApplicationResources.  In  the  application,  a  converter  must 
be  registered  after  Xt  Initialize  but  before  XtGetApplicationResources. 

Within  a  widget,  the  class_initialize  method  is  the  standard  place  to  register  type 
converters.  This  method  is  responsible  for  doing  processing  that  should  be  done  only  once 
when  the  first  instance  of  a  particular  class  is  created. 

Example  9-10  shows  the  code  needed  to  register  the  XmuCvtSt  ringTo  Just  if  y  conver 
ter  in  a  widget  As  noted  above,  this  converter  would  be  used  for  a  resource  (such  as  the 
Athena  Label  widget's  label  resource)  designed  to  give  the  user  the  option  of  justifying 
text  (or  a  graphic  object)  to  the  right,  left,  or  center  of  a  widget* 

Example  9-10.  Registering  a  type  converter 

static  void 
Classlnitialize () 


XtAddConverter (XtRString,    /*  source  type  */ 
XtRJustify,  /*  target  type  */ 

XmuCvtStringTo Justify,  /*  converter  routine 
NULL, 
0); 


/*  args  for  converter  routine  */ 
/*  I  args  for  converter  routine  */ 


The  first  two  arguments  of  XtAddConverter  are  the  source  and  target  type,  respectively, 
specified  using  xtR  symbolic  constants  defined  in  <Xll/StringDefs.h>  (or  defined  in  an 
application  header  file  or  the  widget  public  header  file  if  the  type  is  not  standard  in  Xt). 


*While  it  may  seem  a  little  backwards  to  describe  how  to  add  a  converter  before  we  say  how  to  write  one,  the  avail 
ability  of  the  Xmu  converters  makes  it  likely  that  you  would  in  fact  want  to  add  converters  you  haven't  written. 
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The  third  argument  is  the  name  of  the  converter  routine,  which  by  convention  contains  the 
string  Cvt.  The  Xmu  converters  all  add  the  prefix  Xmu. 

The  fourth  and  fifth  arguments  of  xtAddConverter  are  an  argument  list  that  will  be 
passed  to  the  converter  routine  when  it  is  called.  Some  converter  routines  require  informa 
tion  about  the  context  in  which  the  converter  is  called.  This  is  usually  passed  in  via  an  xt- 
ConvertArgRec  structure,  as  described  in  the  next  section.  If  no  arguments  are  needed, 
the  fourth  and  fifth  arguments  of  XtAddConverter  can  be  NULL. 

9.3.4.1    Passing  Arguments  to  a  Type  Converter 

A  few  type  converters  need  additional  arguments.  For  example,  XmuCvtString- 
Towidget  needs  to  be  passed  the  parent  of  the  current  widget  in  the  application,  so  that  it 
can  compare  the  name  specified  in  the  resource  to  the  names  of  the  children  of  the  passed 
parent  Example  9-11  shows  the  code  used  by  the  Athena  Form  widget  to  register  the  Xmu 
string-to-widget  converter. 

Example  9-11.  Adding  a  converter  with  arguments 

static  void  Classlnitialize () 
{ 

static  XtConvertArgRec  parentCvtArgs [ ]  =  { 
{ 

XtBaseOffset, 

(caddr_t) XtOf f set (Widget,  core .parent) , 
sizeof (Widget) 


XtAddConverter (XtRString, 
XtRWidget, 

XmuCvtStringToWidget, 
parentCvtArgs, 
XtNumber (parentCvtArgs)  )  ; 
} 

The  format  of  the  argument  list  for  XtAddConverter  shown  in  Example  9-12  looks  com 
plicated,  but  in  practice  almost  all  converter  argument  lists  will  look  very  similar  to  the  one 
in  this  example.  The  argument  list  is  specified  as  an  XtConvertArgRec: 

typedef    struct    { 

XtAddressMode    address_mode; 

caddr_t    address_id; 

Cardinal    size; 
}    XtConvertArgRec,     *XtConvertArgList ; 

The  address_mode  field  specifies  how  the  address_id  field  should  be  interpreted. 
The  size  field  specifies  the  length  of  the  data  in  bytes. 

By  specifying  the  address  mode  as  XtBaseOffset  (see  below),  you  can  use  XtOf  f  set 
to  find  the  appropriate  widget  resource,  much  as  you  do  in  an  ArgList.  All  you  have  to  do 
is  change  the  name  of  the  instance  structure  field  (in  this  case  core  .  parent),  and  the  type 
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of  that  field  (in  this  case  widget).  Note  that  the  type  appears  twice,  as  an  argument  to  both 
xtOf f set  and  sizeof . 

The  enumerated  type  XtAddressMode  <XUIConvert.h>)  specifies  the  possible  values  for 
the  address_mode  field: 

typedef  enum  { 

/*  address  mode  parameter  representation  */ 

XtAddress,  /*  address  */ 

XtBaseOffset,  /*  offset  */ 

Xtlmmediate,  /*  constant  */ 

XtResourceString,     /*  resource  name  string  */ 

XtResourceQuark  /*  resource  name  quark  */ 

}  XtAddressMode; 

•  XtAddress  causes  address_id  to  be  interpreted  as  the  address  of  the  data. 

•  XtBaseOffset  causes  address_id  to  be  interpreted  as  the  offset  from  the  widget 
base  address. 

•  Xt  Immediate  causes  address_id  to  be  interpreted  as  a  constant. 

•  XtResourceString  causes  address_id  to  be  interpreted  as  the  name  of  a 
resource  that  is  to  be  converted  into  an  offset  from  the  widget  base  address. 

•  XtResourceQuark  causes  address_id  to  be  interpreted  as  a  quark — that  is,  as  an 
internal  compiled  form  of  an  XtResourceString. 

In  most  cases,  you  will  use  XtBaseOffset,  as  shown  in  Example  9-11. 

When  registering  a  type  converter  in  an  application  rather  than  a  widget,  the  structure  field 
specified  in  the  argument  list  shown  in  the  example  would  be  a  field  of  the  AppData  struc 
ture  instead  of  the  instance  part  structure,  and  widget  would  be  replaced  by  AppData. 

If  any  conversion  arguments  of  type  XtBaseOffset,  XtResourceString,  Xt 
ResourceQuark  and  xtwidgetBaseOf  f  set  are  specified  for  conversions  performed 
by  XtGetApplicationResources,  XtGetSubresources,  XtVaGet- 
ApplicationResources  or  xtVaGetSubresources,  the  arguments  are  computed 
with  respect  to  the  specified  widget,  not  the  base  address  or  resource  list  specified  in  the  call. 

9.3.4.2    Type  Converter  Caching 

Some  type  conversions  are  computationally  expensive  or  require  a  round-trip  request  to  the 
server.  Xt  caches  the  data  returned  from  these  conversions  so  that  a  subsequent  conversion 
of  the  same  source  data  can  be  satisfied  immediately  without  invoking  the  converter  routine 
at  all.  In  other  words,  each  converter  routine  is  not  responsible  for  caching  its  own  returned 
data. 

Xt  caches  the  results  of  only  those  built-in  converters  that  it  is  necessary  to  cache.  However, 
it  caches  the  results  of  all  non-built-in  converters  registered  with  XtAddConverter. 
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9.3.5   Explicitly  Invoking  a  Converter 

Converters  are  normally  invoked  by  Xt  because  the  types  they  convert  are  specified  in  a 
resource  list.  But  this  is  not  the  only  way  in  which  converters  can  be  invoked.  It  is  possible 
to  manually  invoke  type  converters  using  Xt  Convert.  Converter  routines  can  themselves 
invoke  other  converters  directly. 

One  possible  manual  use  of  type  converter  routines  is  in  the  processing  of  the  string  parame 
ters  passed  to  action  routines.  Perhaps  in  the  action  routine  itself  it  is  more  convenient  to 
have  some  parameters  converted  to  another  form.  For  example,  if  an  action  is  passed  the 
string  'TRUE,"  the  action  code  might  prefer  to  convert  this  parameter  to  a  Boolean  value. 
The  CvtStringToBoolean  converter  understands  many  strings  that  would  be  inter 
preted  as  Boolean,  such  as  "Off,"  "On,"  "TRUE,"  "FALSE,"  "No,"  and  "Yes,"  in  upper, 
lower,  or  mixed  case.  It  saves  code  to  use  the  converter  rather  than  comparing  a  string  to  all 
these  strings  in  your  own  code.  Example  9-12  shows  an  action  routine  of  the  Athena  Text 
widget  in  which  a  converter  is  manually  invoked. 

Example  9-12.  Manually  invoking  a  type  converter 

static   void 

DisplayCaret (wr  event,  params,  num_params) 

Widget  w; 

XEvent  *event;  /*  CrossingNotify  special-cased  */ 

String  *params;          /*  Off,  FALSE,  No,  On,  TRUE,  Yes,  etc.  */ 

Cardinal  *num_params;    /*  0,  Ior2*/ 


if  (*num_params  >  0)  {        /*  default  arg  is  "TRUE"  */ 
XrmValue  from,  to; 

from.  size  =  strlen  (from.  addr  =  params  [0]); 
XtConvert(w,  XtRString,  &from,  XtRBoolean,  &to)  ; 
if  (to.  addr  !=  NULL) 

if  (*  (Boolean*)to.addr)  { 

;    /*   parameter   has   boolean   value,    do   something   here    */ 


Note  that  the  from  and  to  arguments  of  Xt  Convert  are  pointers  to  structures  containing 
length/pointer  pairs  —  they  are  not  values.  The  actual  data  is  passed  as  a  pointer  to  a  pointer. 
Thus  the  cast  to  Boolean  references  the  pointer  twice. 

The  widget  argument  of  Xt  Con  vert  is  used  internally  by  Xt  as  the  argument  for  xt- 
Di  splay,  to  get  the  pointer  to  the  display  structure,  and  for  other  purposes.  In  normal 
applications  you  can  pass  any  widget  here.  (For  some  converters,  the  widget  may  need  to  be 
realized.) 

xtConvert  calls  a  lower-level  routine  called  XtDirectConvert.  If  you  prefer,  you 
can  use  this  routine.  Instead  of  passing  it  the  widget  and  the  source  and  destination  type,  you 
pass  it  the  name  of  the  conversion  routine,  and  any  arguments  to  the  routine.  See  Volume 
Five,  X  Toolkit  Intrinsics  Reference  Manual,  for  details. 
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9.3.6   Writing  a  Type  Converter 

If  your  application  or  widget  has  a  data  type  that  you  would  like  the  user  to  be  able  to  set 
through  resource  files,  you  will  need  to  write  (and  register)  a  type  converter  from  xt- 
RString  to  your  type. 

The  first  step  in  creating  a  converter  is  to  decide  upon  the  characteristics  of  the  string  you 
will  be  converting  from,  and  the  C-language  type  you  will  be  converting  to.  Then  you  can 
copy  an  existing  similar  converter  and  fill  in  the  code  to  convert  to  your  desired  type. 
Example  9-13  shows  the  converter  added  by  the  Athena  Form  widget  to  convert  the  "edge 
type"  values  for  its  xtNright,  xtNlef  t,  and  xtNtop  resources. 

This  is  a  good  example  of  the  type  of  converter  you  are  most  likely  to  write.  It  allows  the 
legal  values  for  the  desired  constants  to  be  provided  in  either  case,  and  uses  the  Xlib  quark 
mechanism  to  speed  string  comparison.  Type  converters  (and  the  Xt  and  Xlib  resource  man 
agement  facilities  in  general)  use  quarks  extensively  to  speed  string  comparisons.  A  quark  is 
a  unique  ID  for  a  string,  of  type  XrmQuark  (defined  by  Xlib).  A  call  to  the  Xlib  routine 
XrmStringToQuark  returns  the  quark  for  a  string.  See  Volume  Two,  Xlib  Reference 
Manual,  for  details.  When  a  nonstandard  type  converter  that  uses  quarks  is  defined  and  reg 
istered  in  widget  code,  the  XrmStringToQuark  calls  are  normally  placed  in  the 
class_initialize  method  just  before  the  xtAddConverter  call. 

Example  9-13.  The  XtRString  to  XtREdgeType  type  converter 

/*      This  macro   or   something   like    it   used  by  many  resource   converters 
tdef ine   done (address,    type)    \ 

{    toVal->size   =   sizeof (type) ;    \ 

toVal->addr   =    (caddr_t)    address;    \ 
return;    \ 


/*    This   utility   routine   used   by  many   converters    */ 

void   LowerCase (source,    dest) 

register   char      *source,     *dest; 
{ 

register   char   ch; 

for    (;     (ch  =    *source)     !=   0;    source++,    dest++)     { 
if    ('A'    <=   ch   &&   ch   <=    'Z') 
*dest   =   ch  -   'A'    +   'a' ; 
else 

*dest   =   ch; 
} 
*dest   =   0; 


/*   Quarks  used  to  speed  string  comparisons   */ 

static  XrmQuark  XtQChainLeft,  XtQChainRight,  XtQChainTop, 
XtQChainBottom,  XtQRubber; 
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Example  9-13.  The  XtRString  to  XtREdgeType  type  converter  (continued) 

/*  The  converter  itself  */ 

/*ARGSUSED*/ 

static  void  _CvtStringToEdgeType (args,  num_args,  fromVal,  toVal) 

XrmValuePtr  args;  /*  unused  */ 

Cardinal     *num_args;       /*  unused  */ 

XrmValuePtr  fromVal; 

XrmValuePtr  toVal; 
{ 

static  XtEdgeType  edgeType; 

XrmQuark  q; 

char  lowerName [1000] ; 

Lowercase ( (char*) f romVal->addr,  lowerName) ; 
q  =  XrmSt ringToQuark ( lowerName ); 
if  (q  ==  XtQChainLeft)  { 

edgeType  =  XtChainLeft; 

done (fiedgeType,  XtEdgeType) ; 
} 
if  (q  ==  XtQChainRight)  { 

edgeType  =  XtChainRight; 

done (SedgeType,  XtEdgeType); 
} 
if  (q  ==  XtQChainTop)  { 

edgeType  =  XtChainTop; 

done (SedgeType,  XtEdgeType) ; 
} 
if  (q  ==  XtQChainBottom)  { 

edgeType  =  XtChainBottom; 

done (& edgeType,  XtEdgeType) ; 
} 
if  (q  ==  XtQRubber)  { 

edgeType  =  XtRubber; 

done ( &  edgeType ,  XtEdgeType ) ; 
} 

XtStringConversionWarning(fromVal->addr,  "XtREdgeType") ; 
toVal->addr  =  NULL; 
toVal->size  =  0; 
} 

Notice  that  the  XrmValuePtr  arguments  passed  into  the  converter  are  pointers  to  struc 
tures,  not  values.  The  XrmValue  structure  contains  an  address  field  and  a  size  field. 

XtStringConversionWarning  takes  as  arguments  the  string  that  could  not  be  con 
verted,  and  the  type  to  which  it  could  not  be  converted,  and  issues  a  warning  message  with 
name  conversionError,  type  string,  class  XtToolkitError,  and  the  default 
message  string  "Cannot  convert  "src"  to  type  dst_type."  (See  Chapter  13,  Miscella 
neous  Toolkit  Programming  Techniques,  for  more  information  on  error  and  warning  mes 
sages.) 
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9.3.6.1    Defining  the  Default  Value 

When  performing  conversions,  such  as  from  strings  to  fonts  or  colors,  for  which  there  is  no 
string  representation  that  all  server  implementations  will  necessarily  recognize,  a  type  con 
verter  should  define  some  set  of  conversion  values  that  the  converter  is  guaranteed  to  succeed 
on,  so  that  these  can  be  used  as  resource  defaults. 

For  example,  the  default  string-to-pixel  converter  recognizes  the  symbols  xt Default- 
Foreground  and  XtDef  aultBaclcground.  As  part  of  its  conversion,  it  tests  for  these 
values,  and  establishes  the  appropriate  value  based  on  the  string  value.  The  code  is  shown  in 
Example  9- 14. 

Example  9- 14.  Testing  for  a  special-case  default  value 

if  (Compare I SOLat in 1 (str,  XtDefaultBackground)  ==  0)  { 
*closure_ret  =  FALSE; 

if  (pd->rv)  done (Pixel,  BlackPixelOf Screen (screen) ) 
else         done (Pixel,  WhitePixelOf Screen (screen) ); 
} 
11       if  (ComparelSOLatinl (str,  XtDefaultForeground)  ==  0)  { 

*closure_ret  =  FALSE; 

|1          if  (pd->rv)  done (Pixel,  WhitePixelOf Screen (screen) ) 
else        done (Pixel,  BlackPixelOfScreen (screen) ); 

111:  } 


9.4  Subparts  and  Subresources 

A  subpart  is  a  section  of  a  widget  that  is  replaceable  but  that  cannot  operate  independently. 
It  is  just  a  further  subdivision  of  the  widget  object  into  smaller  pieces. 

Subresources  allow  subparts  of  a  widget  to  have  separate  sets  of  resources.  Since  the  Athena 
Text  widget  is  the  only  example  of  the  use  of  Subresources  in  MIT's  Core  distribution  as  of 
Release  3,  we'll  describe  how  it  uses  subparts  and  Subresources  so  you  can  understand  the 
motivation  behind  them. 

The  Text  widget  has  three  parts:  the  source,  the  sink,  and  the  coordinator  widget  The  source 
manages  the  storage  of  data  and  the  sink  manages  how  it  is  displayed.  The  coordinator  is  the 
central  widget  that  manages  the  communication  between  the  source  and  the  sink,  and  is  inop 
erable  without  them.  Both  the  source  and  the  sink  are  replaceable  pieces  of  code.  Xaw  pro 
vides  only  one  source,  which  edits  a  string  or  disk  file,  and  only  one  sink,  which  displays  text 
in  one  color  and  in  one  font.  The  idea  of  providing  the  subparts  in  the  first  place  is  that  they 
would  allow  enhancements  to  be  made  without  changing  the  basic  editor  functionality  that  is 
in  the  coordinator.  For  example,  only  the  source  and  sink  would  need  replacing  in  order  to 
implement  a  multifont  and/or  multicolor  text  widget 

Each  subpart  has  its  own  resource  list  so  that  it  truly  can  be  replaced  without  any  modifica 
tions  to  the  central  widget  These  are  the  Subresources. 
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The  Hook  Methods 

The  initialize_hook,  set_values_hook  and  get_values_hook  methods  are 
used  by  widgets  that  have  subparts.  They  have  the  same  function  as  their  nonhook  counter 
parts,  except  that  they  process  only  the  resources  of  a  subpart,  and  any  subpart  instance  fields 
that  depend  on  the  subpart  resources.  These  methods  are  called  immediately  after  their 
nonhook  counterparts. 

The  hook  methods  are  called  with  different  arguments  than  their  nonhook  counterparts.  They 
are  passed  a  single  copy  of  the  widget  instance  structure  (the  new  copy  already  modified  in 
the  nonhook  methods),  and  the  argument  list  passed  to  the  Xt  routine  that  triggered  the 
method.  The  set_values_hook  and  get_values_hook  methods  simply  take  this 
widget  ID  and  argument  list  and  pass  them  to  xtSetSubvalues  or  xtGetSubvalues 
respectively.  The  initialize_hook  method  uses  the  contents  of  the  argument  list  to 
validate  resource  settings  for  subparts  and  set  nonresource  subpart  data. 

As  of  Release  4,  the  initialize_hook  and  set_values_hook  methods  are  still 
called  for  backwards  compatibility  but  are  obsolete  because  the  same  information  (the  argu 
ment  lists)  has  been  added  as  arguments  to  the  initialize  and  set_values  methods. 
However,  get_values_hook  is  still  necessary.  Example  9-15  shows  the  get_val- 
ues_hook  for  the  AsciiSrc  subpart  of  the  Text  widget  (somewhat  simplified  to  show  the 
essential  elements). 

Example  9- 15.  Simplified  get_values_hook  method  of  the  AsciiSrc  subpart  of  the  Text  widget 

static   void 

GetValuesHook (src,  args,  num_args) 

XawTextSource  src; 

ArgList  args; 

Cardinal  *  num_args; 


XtGetSubvalues ( (caddr_t)  src, 
sour ceRe sources, 
XtNumber (sourceResources) , 
args, 

*num_args) ; 
} 

The  set_values__hook  method  is  similar  to  the  set_values  method,  except  that  it  is 
passed  only  the  current  widget  instance  structure  and  the  arglist,  instead  of  the  old  and  new 
copies  of  the  widget  instance  structure  which  are  passed  to  set_values.  As  a  result, 
set_values_hook  needs  to  use  a  different  technique  for  comparing  the  current 
subresource  values  with  the  values  set  by  xt  Setvalues. 

There  are  two  ways  to  do  this.  One  is  to  loop  through  the  widget's  resource  list,  using 
strcmp  to  compare  each  resource  name  in  the  argument  list  with  the  subresource  names, 
and  then  comparing  each  argument  value  with  the  current  value  of  the  subresource. 
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The  other  way  is  to  copy  the  instance  structure  passed  in  using  bcopy  (after  allocating 
memory  for  the  new  copy  with  xtNew,  described  in  Chapter  13,  Miscellaneous  Toolkit  Pro 
gramming  Techniques).  Then  call  xtSetSubvalues  to  set  the  actual  values  to  those  in 
the  argument  list.  After  this  process,  you  can  compare  the  old  and  new  values  the  same  way 
this  is  done  in  the  set  values  method. 


9.4.2   Managing  Subresources 

Managing  subresources  is  very  similar  to  managing  application  resources.  Like  the  applica 
tion,  the  subpart  must  have  a  structure  containing  the  fields  to  set  through  resources.  In  the 
application  you  call  xtGetApplicationResources  to  set  these  fields.  In  a  subpart 
the  analogous  call  is  xt Get  Subresources,  which  is  called  from  the 
initialize_hook  method. 

Like  widgets,  the  resources  of  subparts  can  be  queried  and  set  manually.  xtGet- 
Subvalues  queries  the  values,  and  XtSetSubvalues  sets  them.  However,  because 
subvalues  are  not  part  of  any  widget,  these  calls  cannot  identify  what  object  is  being  queried 
or  set  simply  by  passing  the  widget  ID.  These  calls  have  different  arguments  than  xtSet- 
Values  and  xtGetValues.  Instead  of  the  widget  ID,  you  pass  the  pointer  to  the  data 
structure,  the  resource  list,  and  the  number  of  resources.  Therefore,  XtSetSubvalues 
and  xtGetSubvalues  can  be  invoked  only  from  within  the  widget  or  subpart.  Actually, 
all  these  routine  do  is  set  or  get  the  value  in  the  specified  structure. 

Any  application  using  the  widget  will  use  XtSetValues  and  XtGetValues  as  for  nor 
mal  resources,  specifying  only  the  coordinating  widget  as  the  first  argument  These  calls  are 
translated  into  XtSetSubvalues  and  XtGetSubvalues  calls  by  the 
set_values_hook  and  get_values_hook  methods.  These  methods  are  passed  the 
arguments  from  the  XtSetValues  or  XtGetValues  calls  and  translate  them  into  Xt 
SetSubvalues  or  XtGetSubvalues  calls  by  adding  the  data  structure  and  resource 
list  arguments.  But  in  addition,  the  set_values_hook  method  is  responsible  for  validat 
ing  the  resource  settings  passed  in  before  it  calls  XtSetSubvalues,  and  for  changing  any 
nonresource  subpart  structure  fields  like  GCs  that  depend  on  resources. 
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This  chapter  discusses  communication  through  the  X  server  between  an  appli 
cation  and  the  window  manager,  and  between  two  applications.  The  applica 
tion-window  manager  communication  is  performed  by  code  in  the  Shell 
widget.  The  application  sets  shell  resources  to  control  this  communication 
with  the  window  manager.  Application-application  communication  is  usually 
done  with  a  process  called  selections.  This  form  of  communication  is  already 
implemented  in  most  widgets  that  display  text,  but  you  may  want  to  implement 
it  in  your  own  custom  widgets.  Selections  can  also  pass  other  kinds  of  data 
such  as  graphics. 
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Applications  share  the  server  with  other  clients.  Server  resources,  such  as  screen  space  and 
colormaps,  must  be  used  in  a  responsible,  consistent  manner  so  that  applications  can  work 
effectively  together.  In  most  window  systems,  the  window  system  itself  embodies  a  set  of 
rules  for  application  interaction.  However,  the  X  protocol,  Xlib,  and  Xt  were  all  specifically 
designed  to  avoid  arbitrary  conventions,  so  that  they  provide  "mechanism,  not  policy." 

Instead,  the  conventions  covering  interclient  communication  are  described  in  a  separate  doc 
ument,  adopted  as  an  X  Consortium  standard  in  July,  1989,  called  the  Inter-Client  Commu 
nication  Conventions  Manual  (ICCCM).  This  chapter  will  not  fully  describe  the  ICCCM, 
because  the  job  of  implementing  its  rules  is  given  over  to  a  special  client  called  the  window 
manager  and  a  special  widget  class  called  Shell.*  As  a  result  the  details  of  the  ICCCM  are, 
for  the  most  part,  irrelevant  to  the  application  writer's  needs. 

In  X  Toolkit  programs,  the  Shell  widget  returned  by  xtlnitialize  and  used  as  the  top- 
level  window  of  the  application  automatically  handles  most  of  the  required  interactions  with 
the  window  manager.  However,  the  Shell  widget  needs  additional  information  in  certain 
areas.  For  example,  the  application  needs  to  provide  an  icon  pixmap  so  that  the  window 
manager  can  iconify  it  properly.  The  first  section  in  this  chapter  describes  how  to  set  Shell 
resources  to  control  how  an  application  interacts  with  the  window  manager.  This  portion  of 
the  chapter  is  for  application  writers,  regardless  of  whether  you  need  to  write  widgets  for 
your  application. 

In  X  Toolkit  applications,  widgets  can  communicate  with  other  widgets  using  a  mechanism 
called  selections,  which  in  turn  is  based  on  an  X  mechanism  for  common  storage  called  pro 
perties.  Whether  the  widgets  involved  in  transferring  selections  are  part  of  the  same  applica 
tion  or  different  applications  is  irrelevant.  The  communication  between  widgets  takes  place 
without  input  from  the  application.  However,  it  can  be  used  as  a  means  of  communication 
between  applications.  The  second  major  section  in  this  chapter  will  describe  these  concepts 
and  how  to  implement  selections  between  your  own  custom  widgets.  Only  if  your  applica 
tion  requires  a  custom  widget  that  must  communicate  with  other  widgets  should  you  actually 
have  to  write  this  code.  Thus,  this  part  of  the  chapter  is  primarily  for  widget  writers. 


*If  you  do  need  to  look  up  certain  details  of  the  ICCCM,  see  Appendix  F,  Interclient  Communication  Conventions,  in 
a  version  of  Volume  One,  Xlib  Programming  Manual,  printed  on  or  after  February,  1990  (the  conventions  have 
changed  since  earlier  versions  of  Volume  One).  The  ICCCM  is  also  included  in  troff  source  form  in  the  standard  X 
distribution  from  MIT. 


Interclient  Communications  269 


10.1   Window  Manager  Interactions 

The  window  manager  was  introduced  in  Chapter  I, Introduction  to  the  X  Window  System,  but 
little  mention  of  it  has  been  made  since  then.  You  may  recall  that  the  window  manager  is  just 
another  client  running  on  a  server,  except  that  it  is  given  special  authority  to  manage  screen 
space  and  other  limited  server  resources  like  colormaps.*  To  let  the  window  manager  do  a 
better  job  of  mediating  competing  demands  of  the  various  clients,  each  client  gives  the  win 
dow  manager  information  called  window  manager  hints.  These  hints  specify  what  resources 
each  client  would  like  to  have,  but  they  are  only  hints;  the  window  manager  is  not  obligated 
to  honor  them,  and  the  client  must  not  depend  on  them  being  honored. 

Application  code  has  little  to  do  to  interact  properly  with  the  window  manager.  The  Shell 
widget  returned  by  xt Initialize  takes  care  of  setting  the  essential  window  manager 
hints.  However,  there  are  a  number  of  optional  window  manager  hints  that  the  application 
may  wish  to  have  passed  to  the  window  manager.  This  is  done  mainly  by  setting  resources  of 
the  Shell  widget  Also,  there  are  variations  in  window  managers  and  it  takes  some  effort  to 
make  some  applications  work  equally  well  under  all  of  them. 

The  next  few  sections  describe  the  various  resources  of  the  Shell  widget,  including  how  and 
when  they  should  be  set  Because  the  Shell  widget  is  part  of  the  Xt  standard,  these  resources 
are  present  when  writing  applications  with  any  widget  set 

10.1.1    Shell  Subclasses 

There  are  several  types  of  Shell  widgets.  The  Shell  widget  class  itself,  specified  by  the  class 
structure  pointer  shellwidgetClass,  is  never  instantiated  directly  in  applications.  Only 
its  subclasses  are  used.  You  have  seen  two  subclasses  of  the  Shell  widget  used  earlier  in  this 
book,  the  one  used  for  the  application's  top-level  widget  and  the  one  used  for  pop  ups.  The 
application's  top-level  widget  is  created  by  passing  the  class  structure  pointer 
applicationShellwidgetClass  as  the  widget  class  argument  to  xtAppCreate- 
Shell;  this  call  is  also  made  internally  by  xt  initialize.  Pop-up  shells  for  dialog 
boxes  are  created  by  passing  transientShellWidgetClass  as  the  widget  class  argu 
ment  to  XtCreatePopupShell. 

There  are  two  other  subclasses  of  Shell  that  are  commonly  used  in  applications.  One  is  the 
OverrideShellwidgetClass,  passed  to  XtCreatePopupShell  when  the  shell  is 
used  for  pop-up  menus.  The  convention  is  this:  the  shell  should  be  an  OverrideShell  when 
the  pointer  is  grabbed  to  prevent  other  windows  from  getting  input  while  the  pop  up  is  up, 
and  the  shell  should  be  TransientShell  for  other  pop  ups.  This  will  be  discussed  further  in 
Chapter  12,  Menus,  Gadgets,  and  Cascaded  Pop  Ups. 

The  other  additional  subclass  of  Shell  is  topLevelShellwidgetClass,  which  is  used 
to  create  additional,  non-pop-up,  top-level  shells.  Some  applications  have  multiple  perma 
nent  top-level  windows.  One  of  the  top-level  shells  would  be  of  the  application- 


*Note  that  we  are  using  the  term  resources  here  in  a  general  sense,  rather  than  implying  its  Xt-specific  meaning. 
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ShellwidgetClass,  and  the  rest  would  be  of  the  topLevelShellwidgetClass. 
Each  would  have  a  separate  icon. 


10.1.2   Setting  Shell  Resources 

Shell  resources  are  primarily  a  way  for  the  user  and  the  application  to  send  in  data  to  be  com 
municated  to  the  window  manager.  These  window  manager  hints  control  several  major  areas 
of  window  manager  activity:  they  manage  screen  space,  icons,  and  keyboard  input.  We'll 
discuss  these  areas  one  at  a  time  in  the  following  sections.  Table  10-1  lists  the  Shell  widget's 
resources  with  a  brief  description  of  what  they  control,  and  whether  the  application,  the  user, 
or  Xt  normally  sets  them. 

As  indicated  in  Column  3  of  the  table,  some  Shell  resources  are  intended  to  be  set  only  once. 
These  set-once  resources  can  be  left  to  their  default  values,  set  in  the  application-defaults 
file,  or  they  can  be  set  in  the  code  before  the  Shell  widget  is  realized;  but  they  should  not  be 
set  with  xtSetValues  after  realization. 


Table  10-1.  Shell  Resources 


Resource Purpose 


usually  set  by  Shell  itself, 

depending  on  the  subclass : 

XtNargc 

XtNargv 

XtNoverrideRedirect 

XtNtransient 

XtNwaitForWm 

XtNwindowGroup 

XtNwmTimeout 

usually  set  by  user : 

XtNiconX 

XtNiconY 

XtNiconic 

XtNgeometry 

XtNtitle 

usually  set  by  application : 

XtNallowShellResize 

XtNbaseHeight 

XtNbasewidth 

XtNheightlnc 

XtNwidthlnc 

XtNiconMask 

XtNiconName 

XtNiconPixmap 

XtNiconWindow 

XtNinitialState 


Command-line  args  count 

Command-line  args 

Set  for  pop-up  shells  not  to  be  decorated 

Set  for  pop-up  shells 

Whether  to  wait  at  all 

Links  pop  ups  to  main  window 

Waiting  time  for  slow  wm 

Icon  position 

Icon  position 

Sets  XtNinitialState  to  iconic 

Initial  size  and  position 

String  for  tide  bar 

Does  shell  ask  wm  for  size  change? 
Height  of  fixed  components 
Width  of  fixed  components 
Desired  height  increment 
Desired  width  increment 
Mask  used  with  icon  pixmap 
String  for  icon 
Picture  for  icon 
Window  for  icon 
Whether  normal  or  iconic 


When  Sellable 


Before  realization 
Before  realization 
Before  realization 
Before  realization 
Anytime 

Anytime 

Anytime 

Anytime 

Anytime 

Anytime 

Before  realization 

Before  realization 

Before  realization 

Before  realization 

Before  realization 
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Table  10-1.  Shell  Resources  (continued) 


Resource 

Purpose 

When  Sellable 

XtNinput 

Keyboard  input  model 

Before  realization 

XtNmaxAspectX 

Maximum  aspect  ratio  x/y 

Anytime 

XtNmaxAspectY 

Maximum  aspect  ratio  x/y 

Anytime 

XtNmaxHeight 

Maximum  acceptable  height 

Anytime 

XtNmaxWidth 

Maximum  acceptable  width 

Anytime 

XtNminAspectX 

Minimum  aspect  ratio  x/y 

Anytime 

XtNminAspectY 

Minimum  aspect  ratio  x/y 

Anytime 

XtNminHeight 

Minimum  acceptable  height 

Anytime 

XtNminWidth 

Minimum  acceptable  width 

Anytime 

XtNsaveUnder 

Should  server  save  under  when  mapped 

Before  realization 

Several  of  the  Shell  resources  are  set  automatically  by  Xt  or  the  window  manager,  and  under 
normal  circumstances  should  not  be  modified  by  an  application: 

•  The  xtNargc  and  XtNargv  resources  are  set  by  Xt  to  contain  the  command-line  argu 
ments  used  to  invoke  the  application.  This  may  be  used  by  the  window  manager  or  a  ses 
sion  manager  to  allow  the  user  to  reinvoke  the  application  using  the  same  arguments. 

•  The  xtNwindowGroup  resource  is  used  to  link  pop-up  windows  to  an  application's 
main  window.  If  not  set  explicitly,  XtNwindowGroup  is  automatically  set  to  the  top- 
level  ancestor  of  the  pop-up  shell,  which  is  usually  the  application's  top-level  shell. 

•  The  XtNtransient  and  XtNoverrideRedirect  resources  are  set  automatically 
by  Xt  depending  on  what  kind  of  Shell  widget  you  create.   For  top-level  application 
shells,  both  are  set  to  indicate  that  the  window  manager  should  treat  this  window  as  a  top- 
level  window.  For  Transients  hell  pop-up  shells,  XtNtransient  is  set  automatically 
to  the  shell  specified  in  XtNwindowGroup.  When  the  top-level  window  is  iconified, 
the  Transients  hell  pop  up  will  also  be  iconified.    The  Transients  hell  may  also  be 
decorated  differently  from  main  application  shells. 

•  XtNoverrideRedirect  defaults  to  TRUE  in  the  OverrideShell  class,  indicating  that 
the  pop  up  can  map  itself  completely  without  window  manager  intervention.  This  type  of 
pop-up  shell  is  typically  used  for  pop-up  menus,  because  it  grabs  the  pointer  and  no  other 
input  to  other  applications  is  allowed  while  the  menu  is  visible.  This  type  of  pop  up  is 
not  decorated  by  the  window  manager. 

•  The  xtNwaitForWm  and  xtNwmTimeout  resources  control  the  response  to  delays  by 
the  window  manager  in  responding  to  geometry  change  requests.   By  default,  xt- 
NwaitForWm  is  TRUE,  and  XtNwm_timeout  is  five  seconds.  When  making  a  geom 
etry  request  to  the  window  manager,  the  Shell  widget  will  wait  for  five  seconds  for  a 
response.  If  a  response  does  not  arrive  within  five  seconds,  the  Shell  widget  will  set  Xt  - 
NwaitForWm  to  FALSE,  assume  that  the  window  manager  is  not  functioning,  and  con 
tinue,  without  waiting  for  the  event  that  should  arrive  to  represent  the  size  of  the  window, 
and  without  updating  Xt's  internal  cache  of  window  geometries.  When  this  event  does 
arrive  later,  Xt  may  set  XtNwaitForWm  back  to  TRUE  and  update  its  internal  cache. 
These  resources  should  normally  be  left  to  their  default  values. 
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The  XtNgeometry  and  XtNiconic  resources  are  intended  to  be  specified  by  the  user. 
Only  these  two  resources  have  standard  command-line  options  for  setting  them.  The  Xt 
Ngeometry  resource  is  sellable  using  a  command-line  option  of  ihe  form: 

-geometry   [width[x}height][{+-}xposition{  +  - 


(Eilher  the  size  or  position  portion  of  the  geomelry  siring  may  be  omitted,  as  indicated  by  ihe 
square  brackels.  In  specifying  ihe  x  or  y  position,  a  positive  value,  indicated  by  a  plus  sign,  is 
relative  to  the  lop  or  left  side  of  the  reference  window,  while  a  negative  value,  indicated  by  a 
minus  sign,  is  relative  lo  Ihe  bottom  or  right  side.) 

The  -iconic  command-line  option,  if  present,  sels  Ihe  XtNiconic  resource,  indicating  lo 
ihe  window  manager  lhal  ihe  application  should  slart  up  as  an  icon. 

The  xtNicon_x  and  xtNicon_y  icon  position  hinls  are  besl  left  lo  be  specified  by  the 
user.  Icons'  positions  are  determined  by  ihe  window  manager  based  on  ihese  hints  or  on  an 
icon-positioning  policy.  An  application  wilh  several  lop-level  windows  could  sel  ihe  icon 
position  hinls  in  ils  applicalion-defaulls  file  so  that  ihe  icons  for  each  lop-level  window 
appear  side-by-side. 

We  will  discuss  ihe  remaining  resources  in  related  groups.  Section  10.1.3  discusses  ihe  ones 
related  lo  the  size  of  ihe  application's  main  window  and  other  screen  space  issues.  Section 
10.1.4  describes  the  keyboard  input  model  hint.  Section  10.1.5  describes  how  applications 
should  handle  colormaps  lo  cooperate  wilh  ihe  window  manager.  Section  10.1.6  describes 
the  ones  that  apply  to  the  application's  icon. 

10.1.3   Screen  Space 

The  window  manager  directly  controls  Ihe  size  and  position  of  ihe  lop-level  windows  (child 
ren  of  ihe  rool  window)  on  ihe  screen,  ihe  Shell  widgels  of  each  application.  The  window 
manager  does  nol  conlrol  Ihe  geomelry  of  olher  widgels  lhal  are  ihe  descendants  of  ihe 
Shells,  excepl  indireclly  ihrough  ihe  geometry  management  mechanism  described  in  Chapter 
11,  Geometry  Management. 

The  most  basic  size  hinl,  the  one  lhat  specifies  simply  ihe  desired  initial  height  and  width,  is 
automatically  sel  by  Xt  based  on  ihe  size  of  ihe  child  of  ihe  Shell  widget.  This  hint  is  used 
by  most  window  managers  to  display  ihe  outline  of  your  application  when  it  first  appears  on 
the  screen,  ready  for  the  user  lo  place  and/or  size  ihe  application.  If  your  application  does 
not  have  specific  size  needs,  you  need  nol  sel  any  additional  resources. 

The  additional  size  hinls  specify  ihe  application's  range  of  desired  sizes,  desired  incremenls 
of  sizes,  and  desired  range  of  aspecl  ratios.  These  are  set  by  the  xtNbaseHeight,  xt- 
NbaseWidth,  XtNminWidth,  XtNminHeight,  XtNmaxWidth,  XtNmaxHeight, 
XtNwidthlnc,  XtNheightlnc,  XtNminAspectX,  XtNminAspectY,  Xt- 
NmaxAspectX,  and  XtNmaxAspect  Y  resources. 

Size  incremenl  hinls  are  useful  for  applications  lhat  prefer  to  be  in  unils  of  a  particular  num 
ber  of  pixels.  Window  managers  that  listen  for  ihis  hinl  always  resize  ihe  window  lo  ihe  base 
size  (for  each  dimension),  plus  or  minus  an  integral  multiple  of  ihe  size  increment  hint  for 
lhat  dimension.  If  ihe  base  size  resource  has  nol  been  sel,  ihe  minimum  size  is  used  as  the 
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base.  For  example,  xter/n  uses  the  font,  width,  and  height  as  width  and  height  increment 
hints,  because  it  prefers  not  to  have  partial  characters  or  dead  space  around  the  edges.  The 
bitmap  editor  application  described  in  Chapter  4,  An  Example  Application,  should  probably 
set  both  the  width  and  height  increments  to  the  cell_size__in_jpixels,  since  the  bit 
map  cells  are  square. 

Most  applications  that  use  size  increment  hints  redefine  the  interpretation  of  geometry  speci 
fications  (the  xtNgeometry  resource,  sellable  through  the  -geometry  standard 
command-line  option)  to  reflect  the  size  increments.  For  example,  the  width  and  height  in 
xterm  geometry  specifications  are  in  units  of  characters,  not  pixels.  The  VtlOO  widget  within 
xterm  implements  this  by  having  an  XtNgeometry  resource  separate  from  the  shell  geom 
etry  resource  with  that  name.  The  entry  for  this  resource  in  the  widget  resource  list  specifies 
the  VtlOO  instance  structure  field,  not  the  shell  instance  structure  field.  Then  the  realize 
method  for  the  VtlOO  parses  the  geometry  string  with  XParseGeometry  (an  Xlib  routine 
that  returns  four  separate  variables  containing  the  size  and  position  from  the  geometry  string) 
and  sets  the  width  and  height  fields  of  the  core  structure  and  the  various  size  hints  according 
to  the  returned  variables.  (The  VtlOO  within  xterm  is  not  a  real,  self-sufficient  widget  For 
one  thing,  it  has  no  set_values  method.  For  any  real  widget  to  implement  this  approach 
to  interpreting  geometry  specifications,  the  set_values  method  would  have  to  multiply 
the  xtNwidth  and  XtNheight  resource  settings  by  the  increment  hints.) 

An  aspect  ratio  is  the  ratio  of  the  width  measurement  to  the  height  measurement  or  vice 
versa.  The  xtNminAspectx  and  xtNminAspectY  resources  are  used  together  to  deter 
mine  one  extreme  of  acceptable  aspect  ratios,  and  xtNmaxAspectx  and  xt- 
NmaxAspectY  determine  the  other  extreme.  For  example,  to  suggest  that  the  xmh  applica 
tion  never  be  more  than  four  times  larger  in  one  direction  than  it  is  in  the  other,  the  following 
values  (as  they  would  appear  in  the  application-defaults  file)  would  suffice: 

xmh*topLevel .minAspectX:  1 

xmh*topLevel .minAspectY:  4 

xmh*topLevel.maxAspectX:  4 

xmh*topLevel .maxAspectY:  1 

Remember  that  every  application  must  be  able  to  do  something  reasonable  given  any  size  for 
its  top-level  window,  even  if  the  window  is  too  small  to  be  useful  or  if  any  of  these  hints  are 
ignored  by  the  window  manager. 


10.1.4   Input  Model 


Window  managers  also  control  which  window  keyboard  input  will  be  delivered  to  by  setting 
the  keyboard  focus  window  (sometimes  called  just  the  keyboard  focus)  to  an  application's 
top-level  window.  The  distribution  of  events  according  to  the  current  keyboard  focus  is 
handled  by  the  server;  it  is  a  basic  feature  of  X,  not  of  Xt.  Some  window  managers,  like 
UH?n,  use  the  pointer-following  (also  called  real-estate-driven)  model  of  keyboard  input;  the 
window  containing  the  pointer  gets  the  keyboard  input.  Setting  the  keyboard  focus  once  to 
the  root  window  implements  the  pointer-following  model.  Other  window  managers  use  the 
click-to-type  model,  exemplified  by  the  Macintosh™  user  interface,  requiring  that  the  user 
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click  the  pointer  in  the  window  where  keyboard  input  is  to  go.  The  window  manager  sets  the 
keyboard  focus  to  the  window  the  user  clicks  on.  However,  these  basic  window  manager 
behaviors  can  be  modified  by  the  input  model  hint,  which  is  set  by  the  xtNinput  resource. 

If  XtNinput  is  set  to  TRUE,  the  window  manager  will  set  the  keyboard  focus  to  this  appli 
cation  or  not,  according  to  its  pointer-following  or  click-to-type  model  of  keyboard  input. 
However,  if  it  is  set  to  FALSE,  the  window  manager  will  not  set  the  keyboard  focus  to  this 
application.  If  the  application  sets  this  resource  to  FALSE  and  wants  input,  it  will  have  to 
forcefully  take  the  keyboard  focus,  and  then  put  it  back  to  the  original  window  when  fin 
ished. 

For  historical,  not  logical,  reasons,  the  Intrinsics  default  for  the  XtNinput  resource  is 
FALSE.  However,  there  is  a  special  internal  Shell  widget  class  called  VendorShell,  which 
sets  appropriate  resources  for  a  given  widget  set  The  proper  default  for  a  given  widget  set 
(which  usually  has  an  accompanying  window  manager)  is  set  by  that  widget  set's  Vendor- 
Shell.  The  majority  of  applications  need  xtNinput  set  to  TRUE  unless  they  don't  require 
keyboard  input  (and  expect  never  to  have  accelerators). 

There  are  four  models  of  client  input  handling  defined  by  the  ICCCM: 

•  No  Input.  The  client  never  expects  keyboard  input,  xload  is  an  example  of  such  an 
output-only  client.  This  type  of  client  sets  xtNinput  to  FALSE. 

•  Passive  Input.  The  client  expects  keyboard  input  but  never  explicitly  sets  the  input  focus. 
This  describes  the  vast  majority  of  applications  that  always  accept  keyboard  input  in  the 
window  that  contains  the  pointer.  This  type  of  client  sets  xtNinput  to  TRUE. 

•  Locally  Active  Input.  The  client  expects  keyboard  input,  and  explicitly  sets  the  keyboard 
focus,  but  only  does  so  when  one  of  its  windows  already  has  the  focus.  An  example 
would  be  a  client  with  subwindows  defining  various  data  entry  fields  that  uses  Next  and 
Prev  keys  to  move  the  keyboard  focus  between  the  fields,  once  its  top-level  window  has 
received  the  keyboard  focus.  This  type  of  client  sets  XtNinput  to  TRUE. 

•  Globally  Active  Input.  The  client  expects  keyboard  input,  and  explicitly  sets  the  input 
focus  even  when  the  focus  is  in  windows  the  client  does  not  own.  An  example  would  be 
a  client  with  a  scrollbar  that  wants  to  allow  users  to  scroll  the  window  without  disturbing 
the  keyboard  focus  even  if  it  is  in  some  other  window.  It  wants  to  temporarily  set  and 
then  reset  the  keyboard  focus  when  the  user  clicks  in  the  scrolled  region,  but  not  when 
the  user  clicks  in  the  scrollbar  itself.  Thus,  it  wants  to  prevent  the  window  manager  set 
ting  the  keyboard  focus  to  any  of  its  windows.  This  type  of  client  sets  XtNinput  to 

FALSE. 

Note  that  even  if  the  xtNinput  resource  is  not  set  to  TRUE,  your  application  will  still  work 
under  some  window  managers,  including  uwm  and  the  version  of  twm  that  is  standard  in 
Release  4.  This  is  because  these  window  managers  use  the  pointer-following  keyboard  focus 
model  and  ignore  this  hint.  However,  it  is  not  wise  to  assume  that  all  window  managers  will 
ignore  this  hint.  Therefore,  if  your  application  expects  keyboard  input,  and  is  not  of  the  glob 
ally  active  type  described  above,  you  can  use  the  code  shown  in  Example  10-1  to  set  the  xt 
Ninput  resource. 
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Example  10-1.  Setting  the  XtNinput  resource  of  a  Shell  widget 

main(argc,  argv) 
int  argc; 
char  *argv [ ] ; 


static  Arg  shell_args[]  =  { 

{XtNinput,  (XtArgVal)TRUE), 


/*  create  the  Shell  widget  */ 

topLevel  =  Xtlnitialize ("main",  "Xmh",  table,  XtNumber (table) , 
&argc,  argv) ; 


XtSetValues (topLevel,  shell  args,  XtNumber (shell_args) ); 


Note  that  the  XtNinput  resource  should  always  be  hardcoded,  since  the  application  may 
fail  if  the  user  is  allowed  to  change  the  expected  style  of  keyboard  focus. 

For  a  further  discussion  of  the  keyboard  focus,  see  Section  13.3. 


10.1.5   Colormaps 


On  most  color  systems,  the  display  uses  one  or  more  hardware  registers  called  colormaps  to 
store  the  mapping  between  pixel  values  and  actual  colors,  which  are  specified  as  relative 
intensities  of  red,  green,  and  blue  primaries  (RGB  values). 

X  allows  virtual  colormaps  to  be  created  by  applications.  Some  high-performance  systems 
even  allow  all  virtual  colormaps  to  be  installed  in  hardware  colormaps  and  used  at  the  same 
time,  even  to  the  level  of  one  colormap  per  window.  Far  more  commonly,  though,  there  is 
only  one  hardware  colormap,  and  virtual  colormaps  have  to  be  copied  into  the  hardware 
colormap  one  at  a  time  as  needed.  Copying  a  virtual  colormap  into  the  hardware  colormap  is 
called  installing  the  colormap,  and  the  reverse  process  where  the  default  colormap  is 
installed  is  called  uninstalling .  The  window  manager  is  responsible  for  installing  and  unins- 
talling  colormaps. 

If  your  application  has  standard  color  needs  (decoration  only),  then  you  do  not  have  to  worry 
about  the  effects  of  colormaps  being  installed  and  uninstalled.  Your  application  should  use 
the  standard  xtRString  to  xtRPixel  converter  to  translate  color  names  into  pixel  val 
ues.  If  the  colormap  is  full,  or  becomes  full  at  any  of  the  color  allocations  in  the  converter, 
the  warning  messages  place  the  burden  on  the  user  to  kill  some  applications  in  order  to  free 
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some  colormap  cells.  (If  the  converter  cannot  allocate  the  desired  color,  it  prints  a  warning 
message,  and  the  default  for  that  resource  is  used.  If  the  default  is  not  xtDefault- 
Foreground  or  XtDef  aultBackground,  it  also  must  be  converted  and  this  may  also 
fail.  If  both  allocations  fail,  the  color  will  default  to  black.  If  this  is  not  acceptable,  then  you 
will  need  to  write  your  own  type  converter.) 

If  your  application  absolutely  requires  accurate  colors,  a  certain  number  of  distinguishable 
colors,  or  dynamically  changeable  colors,  you  will  need  to  write  your  own  converter  to  allo 
cate  colors.  For  example,  if  a  color  allocation  for  a  known  correct  color  name  string  fails,  it 
means  that  all  the  colormap  entries  have  already  been  allocated  and  no  entry  for  that  color  is 
available.  In  this  case,  your  converter  might  call  the  Xlib  call  XGopyColormapAndFree 
to  copy  the  allocations  your  application  has  already  made  into  a  new  colormap.  Then  the 
converter  would  allocate  the  color  (and  all  subsequent  colors)  from  the  new  colormap. 

See  Chapter  7,  Color,  in  Volume  One,  Xlib  Programming  Manual,  for  details  of  various  color 
allocation  techniques. 

The  window  manager  is  responsible  for  installing  and  uninstalling  colormaps  according  to  its 
own  policy.  Typically,  the  policy  is  to  install  the  colormap  of  the  application  that  has  the 
keyboard  focus  or  that  contains  the  pointer.  When  an  application  has  created  a  new  colormap 
on  a  system  that  supports  only  one  hardware  colormap,  and  that  colormap  is  installed,  all 
applications  that  were  using  the  other  colormap  will  be  displayed  using  the  new  colormap. 
Since  the  pixel  values  from  the  old  colormap  have  not  been  allocated  in  the  new  colormap, 
all  applications  that  use  the  old  colormap  will  be  displayed  with  false  colors.  This  is  known 
as  "going  technicolor." 

The  window  manager  may  also  create  standard  colormaps  to  facilitate  the  sharing  of  colors 
between  applications.  A  standard  colormap  is  a  colormap  allocated  with  a  publicly  known 
arrangement  of  colors.  The  Xlib  routine  XGetStandardColormap  allows  an  applica 
tion  to  determine  whether  the  window  manager  has  created  a  specific  standard  colormap,  and 
it  gets  a  structure  describing  the  colormap. 


Icons 

The  window  manager  always  manages  the  icons  for  each  application.  Depending  on  the  win 
dow  manager,  these  icons  may  simply  contain  a  text  string  called  the  icon  name,  or  they  may 
contain  a  pattern  that  identifies  the  application,  called  the  icon  pixmap. 

Figure  10-1  shows  the  icon,  under  the  uwm  window  manager,  for  an  application  with  a  cus 
tom  icon  pixmap  (xcalc)  and  for  one  without  (xterm). 
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Figure  10-1.  An  icon  with  and  without  an  icon  pixmap 

An  application  may  supply  an  icon  name  by  setting  the  XtNiconName  resource;  if  it  does 
not,  the  window  manager  will  usually  use  the  application  name  or  the  value  of  the  xt- 
Nti tie  resource. 

The  application  should  supply  the  pattern  for  the  icon,  in  the  form  of  a  single-plane  pixmap, 
as  the  xtNiconPixmap  resource.  There  are  two  basic  ways  to  do  this:  one  is  by  including 
bitmap  data,  and  the  other  is  by  reading  it  in  at  run-time.  The  former  is  easy  to  do  with  an 
Xlib  call;  the  code  that  needs  to  be  added  is  shown  in  Example  10-2.  The  latter  technique, 
because  it  involves  building  a  filename  and  looking  in  a  number  of  locations  for  the  file,  is 
better  done  with  a  converter  defined  by  the  Xmu  library.  This  converter  technique  is  more 
complicated  because  the  converter  has  to  be  registered  and  called  with  the  proper  arguments. 
The  example  using  a  converter  is  provided  in  the  example  source  code,  but  not  shown  here. 
See  Chapter  9,  Resource  Mangement  and  Type  Conversion,  for  more  information. 

Example  10-2.  Creating  an  icon  pixmap,  and  setting  XtNiconPixmap 


/*  both  R3  and  R4  (part  of  Xt)  */ 

tinclude  <Xll/Shell .h>  /*  Athena  Label  Widget  */ 

tinclude  "icon. bit" 

main(argc,  argv) 
int  argc; 
char  **argv; 
{ 

Pixmap  icon_pixmap; 

Arg  arg; 


/*  create  topLevel  here  */ 

icon_pixmap  =  XCreateBitmapFromData (XtDisplay (topLevel)  , 
RootWindowOf Screen (XtScreen (topLevel) ) , 
icon_bits, 
icon_width,  icon_height  ) ; 
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Example  10-2.  Creating  an  icon  pixmap,  and  setting  XtNiconPixmap  (continued) 

XtSetArg(arg,    XtNiconPixmap,    icon_pixmap) ; 
XtSetValues (topLevel,    &arg,    1); 


/*    realize   widgets    */ 

The  included  file,  icon.bit,  is  in  standard  XI 1  bitmap  file  format.  You  can  create  such  a  file 
using  the  bitmap  application. 

The  window  manager  may  have  a  preferred  standard  size  for  icons.  If  so,  it  will  set  a  prop 
erty.  The  application  can  read  this  property  with  the  Xlib  call  XGetlconSizes.  To  fully 
support  a  variety  of  window  managers,  an  application  should  be  capable  of  creating  icon  pix- 
maps  of  different  sizes,  depending  on  the  values  returned  by  XGetlconSizes. 

10.1.7  Window  Manager  Decorations 

Most  window  managers,  with  the  exception  of  uwmt  decorate  windows  on  the  screen.* 
These  decorations  typically  include  a  title  bar  for  the  window  with  widgets  for  moving  and 
resizing  the  window.  Current  decorating  window  managers  include  twm,  awm,  mwm,  olwm, 
and  gwm. 

The  way  these  decorations  are  implemented  can  have  an  impact  on  Toolkit  applications.  The 
window  manager  places  the  decorations  in  a  window  slightly  bigger  than  the  application,  and 
then  reparents  the  application's  top-level  window  into  the  decoration  window.  Reparenting 
gives  the  top-level  window  a  new  parent  instead  of  the  root  window.  The  window  manager 
actually  creates  the  frame  window  as  a  child  of  the  root  window,  then  reparents  the  applica 
tion's  top-level  window  into  the  frame,  and  then  maps  the  frame  window. 

Reparenting  impacts  the  application  mainly  when  you  try  to  determine  a  global  position  (rel 
ative  to  the  root  window)  from  the  xtNx  and  xtNy  resources  of  the  Shell  widget  This  is 
usually  done  to  place  pop  ups.  Under  a  nonreparenting  window  manager  such  as  uwm,  these 
coordinates  are  indeed  relative  to  the  root  window,  because  the  parent  of  the  shell  is  the  root 
window.  However,  under  a  window  manager  that  reparents  transient  shells,  the  coordinates 
are  relative  to  the  decoration  window,  not  the  root  window.  Therefore,  these  coordinates  can 
not  be  used  for  placing  pop  ups  within  the  application.  The  code  shown  in  Section  3.3  that 
places  a  pop  up  uses  xtTranslateCoords  instead  of  relying  on  the  position  resources. 


*The  uwm  window  manager  will  no  longer  be  supported  by  the  X  Consortium  as  of  Release  4.  Then,  virtually  all 
window  managers  will  be  of  the  decorating,  reparenting  type. 
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10.2  Selections:  Widget-To-Widget  Communication 

Selections  are  a  general  mechanism  for  communicating  information  between  two  clients  of 
the  same  server.  The  most  familiar  example  of  selections  is  selecting  text  from  one  xterm 
application  and  pasting  it  into  another  xterm  application.  This  text  can  also  be  pasted  into  an 
xmh  mail  composition  window,  or  into  an  xedit  application. 

In  Xt  applications,  selection  is  normally  implemented  within  widgets.  For  example,  the 
Athena  Text  widget  is  used  by  xmh  and  xedit ,  and  it  is  this  widget  that  supports  cutting  and 
pasting  of  text  in  these  applications.  The  application  code  of  xmh  and  xedit  does  not  play  a 
part  in  the  communication  of  selection  data.  The  fact  that  selection  is  implemented  in  wid 
gets  also  means  that  two  widgets  within  the  same  application  can  communicate  with  each 
other  through  selections.  For  example,  the  Text  widget  is  sometimes  used  to  provide  single- 
line  input  fields  in  an  application.  Since  the  Text  widget  supports  selections,  the  user  could 
select  the  text  in  one  field  and  paste  it  into  another  field.  This  feature  would  be  present  with 
out  any  code  in  the  application.  If  the  same  widget  class  supports  both  copying  and  pasting, 
selections  can  be  used  to  move  data  in  a  single  widget  For  example,  selections  allow  you  to 
copy  text  within  an  editor  in  xterm  and  paste  the  text  in  a  new  place  (although  some  editors 
require  keyboard  commands  to  position  the  insertion  point). 

The  selection  mechanism  is  not  limited  to  text  It  requires  only  that  the  sender  and  recipient 
have  knowledge  of  the  format  of  the  data  being  transferred.  Therefore,  selections  can  be 
used  to  transfer  graphics  between  widgets  that  can  understand  a  common  format  for  com 
municating  graphics.  Unfortunately,  a  standard  format  for  graphics  has  not  yet  been  agreed 
upon. 

The  selection  mechanism  uses  properties  for  transferring  data  and  uses  the  Selection- 
Clear,  SelectionNotif  y,  and  SelectionRequest  event  types  to  synchronize  the 
communication.  Essentially,  a  property  is  common  storage.  Properties  are  stored  in  the 
server,  and  are  named  pieces  of  data  associated  with  a  window  on  that  particular  server,  that 
any  client  of  that  server  can  read  or  write.  Because  the  various  clients  may  not  be  running  on 
the  same  host,  all  communication  between  applications  and  between  applications  and  the 
window  manager  must  take  place  through  the  server  using  properties.* 

The  basic  routines  used  to  implement  selections  are  part  of  Xlib.  Xt  provides  an  interface  to 
the  Xlib  selection  routines  that  makes  selections  easier  to  use  in  the  context  of  widget  code. 
Since  there  is  a  maximum  size  for  the  data  stored  in  a  single  property,  communication  of 
large  blocks  of  data  using  Xlib  requires  several  partial  transfers.  Xt  supplies  routines  that 
transparently  perform  the  multiple  partial  transfers  so  that  they  appear  to  the  application  pro 
gram  like  a  single  transfer.  The  Toolkit  selection  routines  also  provide  timeouts,  so  that  one 
application  won't  wait  forever  for  another  to  provide  data. 


*It  is  not  even  possible,  in  general,  to  write  your  own  networking  routines  in  an  application  to  communicate  with  oth 
er  clients  running  on  different  hosts,  because  your  client  may  be  communicating  with  the  server  using  TCP/IP  and  the 
other  client  may  be  using  DECneL  Both  may  be  the  same  X  application  that  you  wrote,  but  compiled  with  a  version 
of  Xlib  that  uses  a  different  protocol  layer  underneath  the  X  protocol.  When  you  communicate  through  the  server  us 
ing  properties,  the  server  takes  care  of  the  translation. 
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First  we'll  give  you  an  overview  of  how  a  selection  transaction  works,  and  then  we'll  discuss 
how  to  write  the  code  to  implement  selections  in  a  widget 

If  you  are  writing  a  custom  widget  that  contains  data  that  could  be  pasted  into  other  instances 
of  the  widget  or  other  widgets,  you  should  read  on  to  see  how  to  implement  selections. 
Otherwise,  the  rest  of  this  chapter  is  probably  only  of  academic  interest  to  you. 

How  Selection  Works 

Selections  communicate  between  an  owner  widget  and  a  requestor  widget*  The  owner  has 
the  data  and  the  requestor  wants  it  The  owner  is  the  widget  in  which  the  user  has  selected 
something,  and  the  requestor  is  the  widget  in  which  the  user  has  clicked  to  paste  that  some 
thing.  Many  widgets  need  to  act  as  both  owner  and  requester  at  different  times.  The  code  to 
handle  each  of  the  two  roles  is  separate. 

Here  is  a  brief  overview  of  the  steps  that  take  place  during  a  single  transfer  of  data  from  one 
widget  to  another.  We'll  assume  we  have  two  instances  of  the  same  widget  class,  which  can 
operate  either  as  the  owner  or  the  requestor.  Initially,  both  widgets  are  in  exactly  the  same 
state,  neither  having  any  text  selected,  and  neither  being  the  owner  or  requestor.  We'll  also 
assume  that  selections  are  implemented  using  actions  tied  to  pointer  buttons,  as  in  existing 
widgets  that  use  selections. 

•  The  user  selects  an  item  in  Widget  A,  and  the  widget  highlights  the  item.  An  action,  typi 
cally  called  in  response  to  a  <BtnlDown>  translation,  marks  the  start  of  a  selection.  A 
subsequent  <BtnlMotion>  event  (that  is,  a  motion  event  with  button  1  held  down) 
invokes  another  action  to  extend  the  highlighted  selection. 

•  A  <BtnlUp>  event  invokes  a  third  action  in  Widget  A  that  actually  makes  the  selection. 
The  action  calls  xtOwnSelection  to  claim  ownership  of  the  PRIMARY  selection  for 
Widget  A.  This  means  that  Widget  A  claims  the  sole  right  to  use  the  XA_PRIMARY  prop 
erty  for  communication  with  other  widgets,  until  some  other  widget  claims  ownership. 
(More  about  XA_PRIMARY  below.)  The  call  to  XtOwnSelection  also  registers  three 
procedures,     to    be     called     by     Xt    in    response    to    selection     events.      The 
lose_ownersh±p_proc  handles  the  case  where  Widget  A  loses  the  selection 
(because  the  user  has  made  another  selection  elsewhere),  the  convert_proc  converts 
the  data  in  the  selection  to  the  target  property  type  requested  by  Widget  B  (see  below), 
and  the  optional  trans fer_done_proc  prepares  for  the  next  selection  request,  if 
necessary  (this  function  is  often  NULL). 

•  The  user  pastes  the  item  into  Widget  B,  usually  by  clicking  a  pointer  button.  (By  conven 
tion,  a  translation  for  <Btn2Down>  invokes  the  action  to  do  this.) 

•  The  paste  action  in  Widget  B  requests  the  value  of  the  current  selection  by  calling  xt- 
GetSelectionValue;  this  specifies  a  target  type,  and  a  requestor_callback 
that  will  be  invoked  to  actually  paste  the  data  when  Widget  A  reports  that  the  conversion 
has  been  successfully  completed. 


*Note  that  since  selections  can  be  implemented  in  the  application,  as  they  are  non-Xt  applications,  the  words  "appli 
cation"  and  "widget"  are  interchangeable  in  this  section. 
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•  The  XtGetSelectionValue  call  by  Widget  B  also  generates  a  Selection- 
Request  event  In  response  to  this  event,  Xt  invokes  the  convert_jproc  registered 
by  the  call  to  XtOwnSe  lection  in  Widget  A. 

•  The  convert_proc  in  Widget  A  converts  the  selected  item  into  the  appropriate  data 
type  for  the  target  property  specified  by  5,  if  possible.  The  converted  data  is  stored  in  the 
XA_PRIMARY  property. 

•  Based  on  the  return  values  from  Widget  A's  conversion  procedure,  Xt  sends  a 
SelectionNotif  y  event  to  inform  Widget  B  whether  or  not  the  data  was  success 
fully  converted. 

•  The  request or_callback  registered  in  Widget  B  reads  the  data  from  the  property 
and  displays  it,  or  if  Widget  A  reported  that  the  conversion  could  not  be  made,  Widget  B 
beeps  or  otherwise  indicates  that  the  kind  of  data  selected  in  Widget  A  cannot  be  pasted 
in  Widget  B,  or  that  the  kind  of  data  requested  by  B  cannot  be  supplied  by  A. 

•  Xt  notifies  Widget  A  that  the  selection  has  been  transferred,  so  that  the  widget's 
trans  fer_done_proc  can  disown  the  selection  if  the  selection  is  of  a  kind  that  can 
be  transferred  only  once. 

Figure  10-2  shows  this  procedure  in  graphic  form. 

The  code  to  implement  selections  is  divided  logically  into  a  number  of  functions  within  the 
widget  The  next  sections  show  the  code  necessary  to  implement  both  the  owner  and  the 
requestor  roles.  The  code  for  each  role  is  separate  and  cannot  share  any  widget  variables 
with  the  other  role  because  the  transaction  may  be  between  two  different  widget  instances. 

As  an  example,  we  will  add  support  for  selections  to  the  BiimapEdit  widget  described  in 
Chapter  5  and  Chapter  6.  Little  of  the  existing  code  in  that  widget  needs  to  be  changed.  The 
examples  show  only  the  code  added  to  implement  selections,  and  describe  where  to  add  it 

We  will  start  with  the  owner  role,  and  then  proceed  to  the  requestor  role,  and  then  back  to  the 
owner  role. 


282  X  Toolkit  Intrinsics  Programming  Manual 


user  presses 
button  1  and 
makes  selection 


convert _proc  converts 
data  and  returns.  Xt 
sets  property 


XtOwnSelection 
registers  3 
procedures 


H  user  presses 
U  button  2  to 
paste 
selection 

XtGetSelectionValue  Me 
sends                       I 
SelectionRequest 
event  to  owner 

\ 

o  j  Xt  sends 
°    SelectionNotify 
event 


ntrinsics 
routines 


XtGetSelectionValue () 


XtGetSelectionValue 
registers  callback  to 
do  actual  paste 


Xt  invokes* 
requestor  callback, 
which  actually 
pastes  the  data 


widgetA. translations :  \n\ 
<BtnlDown>:  startHighlight ( )  \n\ 
<BtnlMotion>:  extendHighlight ( )  \n\ 
<BtnlUp>:  makeSelection  ( ) 


widgetB. translations :  \n\ 
<Btn2Down>:  paste () 


Figure  10-2.  The  process  of  selection  transfer 
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10.2.2    Highlighting  the  Selected  Data  (Owner) 

The  selection  process  begins  when  the  user  selects  some  text  in  Widget  A.  The  widget  code 
for  the  owner  role  must  contain  some  code  to  identify  the  area  or  items  selected  and  to  high 
light  the  text  (or  whatever)  being  selected.  This  user-interface  portion  of  the  owner  role  is 
carried  out  by  actions  added  to  the  widget  Some  event  sequences  that  are  not  already  in  use 
must  be  mapped  to  these  actions.  In  existing  applications  that  support  selections  of  text: 

•  A  press  of  the  first  pointer  button  pins  a  starting  point  of  the  selection,  dragging  the  first 
button  extends  and  highlights  the  selection,  and  releasing  the  first  button  ends  the  selec 
tion.  A  subsequent  press  of  the  first  button  starts  a  new  selection,  unhighlighting  the  old 
one. 

•  A  press  of  the  second  button  pastes  the  selection. 

•  A  button  press  or  motion  with  the  third  button  depressed  repositions  either  end  of  the 
selected  area. 

It  is  a  good  idea  to  stick  with  existing  conventions  for  the  user  interface  of  highlighting  a 
selection,  so  that  your  application  will  operate  in  a  familiar  way.  But  since  BitmapEdit 
already  uses  all  three  pointer  buttons,  unmodified,  to  set,  unset,  and  toggle  bitmap  cells,  we 
cannot  use  unmodified  button  presses  to  control  selections.  But  we  can  (and  will)  use  these 
same  buttons  modified  by  Shift. 

A  selection  in  BitmapEdit  is  any  rectangular  set  of  bitmap  cells.  Accordingly,  BitmapEdit 
will  use  Shift<BtnlDown>  to  set  the  top-left  corner  of  a  selection  rectangle, 
Shif  t<BtnlMotion>  to  follow  dragging,  and  Shif  t<BtnlUp>  to  set  the  bottom  right 
corner.*  Each  of  these  events  will  invoke  a  separate  action  routine,  StartHighlight, 
ExtendHighlight,  and  MakeSelection,  respectively.  These  translations  are  added 
to  the  widget's  default  translation  table,  and  the  actions  are  added  to  the  actions  table. 
Example  10-3  shows  the  action  table,  the  translation  table,  and  the  three  action  routines. 


Example  10-3.  BitmapEdit:  actions  that  highlight  selection 

static  char  defaultTranslations [ ]  = 


'Shif t<BtnlDown> : 
Shif t<BtnlMotion> : 
Shift <BtnlUp>: 
Shif t<Btn2Down> : 
'Shift <BtnlDown> : 
"Shif t<Btn2Down> : 
~Shift<Btn3Down>: 
~Shift<BtnlMotion>: 
'Shift <Btn2Motion> : 
'Shif t<Btn3Motion> : 


StartHighlight () 
ExtendHighlight () 
MakeSelection () 
PasteSelection () 
DoCellO 
UndoCelK) 
ToggleCelK) 
DoCellO 
UndoCelK) 
ToggleCell ()"; 


\n\ 
\n\ 
\n\ 
\n\ 
\n\ 
\n\ 
\n\ 
\n\ 
\n\ 


static  XtActionsRec  actions!]  =  { 
{"DoCell",  DoCell}, 
{"UndoCell",  UndoCell}, 
{"ToggleCell",  ToggleCell}, 


*For  simplicity,  we  won't  copy  the  third  button  semantics  used  in  text  selections.  This  could  easily  be  added. 
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Example  10-3.  BitmapEdit:  actions  that  highlight  selection  (continued) 

("StartHighlight",  StartHighlight}, 
{"ExtendHighlight",  ExtendHighlight}, 
{ "MakeSelection",  MakeSelection} , 
{ "PasteSelection",  PasteSelection } , 


static  void 

StartHighlight (w,  event) 
BitmapEditWidget  w; 
XButtonEvent  *event; 

w->bitmapEdit .first_box  =  FALSE; 

w->bitmapEdit . select_start_x  =  (w->bitmapEdit .cur_x  + 
event->x)  /  w->bitmapEdit .cell_size_in_pixels; 

w->bitmapEdit . select_start_y  =  (w->bitmapEdit .cur_y  + 
event->y)  /  w->bitmapEdit .cell_size_in_pixels; 

/*  clear  old  selection  */ 
Redisplay (w,  NULL); 

static  void 

MakeSelection (w,  event) 
BitmapEditWidget  w; 
XButtonEvent  *event; 

int  temp; 

w->bitmapEdit . select_end_x  =  (w->bitmapEdit .cur_x  + 

event->x)  /  w->bitmapEdit . cell_size_in_pixels, 

w— >bitmapEdit . select_end_y  =  (w->bitmapEdit ,cur_y  + 

event->y)  /  w->bitmapEdit . cell_size_in_pixels, 

if  ( (w->bitmapEdit . select_end_x  == 

w->bitmapEdit . select_start_x)  && 
(w->bitmapEdit . select_end_y  == 
w->bitmapEdit . select_start_y) )   { 

Redisplay (w,  NULL); 

return;  /*  no  selection  */ 

/*  swap  start  and  end  if  end  is  greater  than  start  */ 
if  (w->bitmapEdit . select_end_x  < 

w->bitmapEdit . select_start_x)  { 

temp  =  w->bitmapEdit . select_end_x; 

w->bitmapEdit . select_end_x  = 

w->bitmapEdit . select_start_x; 

w->bitmapEdit . select_end_x  = 

w->bitmapEdit . select_start_x; 

w->bitmapEdit . select_start_x  =  temp; 

if  (w->bitmapEdit . select_end_y  < 

w->bitmapEdit . select_start_y)  { 
temp  =  w->bitmapEdit . select_end_y; 
w->bitmapEdit . select_end_y  = 
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Example  10-3.  B'rtmapEdit:  actions  that  highlight  selection  (continued) 

w->bitmapEdit  .  select_start_y; 
w->bitmapEdit  .  select_start_y  =  temp; 

} 

if  (XtOwnSelection  (w,  XA_PRIMARY,  event->time,  convert_proc, 
lose_ownership_proc, 
transf  er_done_proc)  ==  FALSE)  { 
XtWarning  ("bitmapEdit  :  failed  to  become  selection\ 

owner;  make  a  new  selection  .  \n")  ; 
/*  Clear  old  selection,  because  lose_ownership_proc 

*  isn't  registered.  */ 
Redisplay  (w,  NULL); 


static  void 

ExtendHighlight  (w,  event) 
BitmapEditWidget  w; 
XMotionEvent  *event; 
{ 

static  int  last_drawn_x,  last_drawn_y; 

int  event_cell_x,  event_cell  y; 

event_cell_x  =  w->bitmapEdit  .  cur_x  +  (event->x  / 

w->bitmapEdit  .  cell_size_in_pixels)  ; 
event_cell_y  =  w->bitmapEdit  .  cur_y  +  (event->y  / 

w->bitmapEdit  .  cell_size_in_pixels)  ; 

if  (  (event_cell_x  ==  last_drawn_x)  &&  (event_cell_y  == 

last_drawn_y  )  ) 
return; 

if  (w->bitmapEdit  .  first_box)  { 

draw_box(w,  last_drawn_x,  last_drawn_y)  ;   /*  undraws  */ 

draw_box(w,  event_cell_x,  event_cell_y)  ; 
} 
else  { 

draw_box(w,  event_cell_x,  event_cell_y)  ; 

w->bitmapEdit  .  first_box  =  TRUE;~ 
} 

last_drawn_x  =  event_cell_x; 
last_drawn_y  =  event_cell_y; 
i 

static  void 
draw_box(w,  x,  y) 
BitmapEditWidget  w; 
Position  x,  y; 
{ 

Position  start_pos_x,  start_pos_y; 

Dimension  width,  height; 

start_pos_x  =  w->bitmapEdit  .  cur_x  + 

w->bitmapEdit  .  select_start_x; 
start_pos_y  =  w->bitmapEdit  .  cur_x  + 

w->bitmapEdit  .  select_start_y; 

/*    swap    start    and   end    if   end    is    greater   than    start    */ 
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Example  10-3.  BitmapEdit:  actions  that  highlight  selection  (continued) 

if  (x  <  start_pos_x)  { 

width  =  start_pos_x  -  x; 

start_pos_x  =  x; 
} 
else  { 

width  =  x  -  start_pos_x; 
} 

if  (y  <  start_pos_y)  { 

height  =  start_pos_y  -  y; 

start_pos_y  =  y; 
} 
else  { 

height  =  y  -  start_pos_y; 
} 

XDrawRectangle (XtDisplay (w) ,  XtWindow (w) , 

w->bitmapEdit . xor_gc,  (start_pos_x  * 
w->bitmapEdit .cell_size_in_pixels)  •-  1, 
(start_pos_y  *  w->bitmapEdit .cell_size_in_pixels)  •-  1, 
(unsigned  int)  width  * 

w->bitmapEdit . cell_size_in_pixels  +  2, 
(unsigned  int)  height  * 

w->bitmapEdit .cell_size_in_pixels  +  2); 
} 

The  actions  shown  in  Example  10-3  reference  some  new  instance  part  fields  we  have  added 
to  BitmapEditP .h  to  store  the  state  of  the  selection.  Four  of  these  variables  are  the  x  and  v; 
coordinates  in  cells  of  the  top-left  and  bottom-right  corners  of  the  highlighted  area: 
select_start_x,  select_start_y,  select_end_x,  and  select_end_y. 
These  will  be  used  throughout  the  owner  code.  (Because  these  fields  are  in  units  of  bitmap 
cells,  not  pixels,  their  type  is  int  rather  than  Position.) 

The  Start  Highlight  action  is  quite  simple.  It  sets  the  upper-left  corner  instance  part 
fields  based  on  the  button  press  position  in  the  triggering  event.  It  also  clears  the  highlight 
ing  of  the  old  selection,  if  one  exists,  and  sets  a  flag  to  indicate  that  this  is  the  beginning  of  a 
new  selection.  The  f  irstjbox  flag  is  added  as  an  instance  part  field  because  it  will  be 
needed  in  the  ExtendHighlight  action. 

ExtendHighlight  is  responsible  for  drawing  a  dynamic  rubber-band  box  around  the 
selected  area,  much  as  the  window  manager  draws  the  outline  of  a  window  while  it  is  being 
moved.  This  outline  surrounds  a  rectangle  of  bitmap  cells  beginning  from  the  cell  selected  in 
the  StartHighlight  action  and  ending  at  the  cell  the  pointer  is  currently  in.  Extend 
Highlight  is  triggered  by  pointer  motion  events  that  occur  while  the  first  button  is  held 
down.  It  calculates  which  bitmap  cell  the  pointer  is  in,  and  if  the  cell  is  not  the  same  as  the 
cell  the  pointer  was  in  the  last  time  ExtendHighlight  was  called,  it  erases  the  previous 
box  and  draws  a  new  one.  The  most  efficient  way  to  draw  such  a  box  so  that  it  can  be  erased 
easily  is  to  use  the  exclusive  OR  logical  function  in  the  GC.*  We've  added  another  GC  field 
to  the  instance  part  structure  to  hold  a  GC  set  to  this  logical  function,  and  added  code  to  the 


*With  exclusive  OR,  drawing  once  draws  the  box,  and  drawing  it  again  erases  the  box.  This  works  on  both  color  and 
monochrome  screens,  but  only  if  nothing  is  drawn  between  the  drawing  operations.  See  Chapter  7,  Color,  in  Volume 
One,  Xlib  Programming  Manual,  for  more  information. 
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initialize  method  to  create  this  GC.  (See  xbitmap  in  the  example  distribution  for  this 
modified  widget  instance  structure.) 

The  MakeSelection  action  is  triggered  when  the  button  is  released  after  dragging,  indi 
cating  that  the  selection  is  complete.  This  action  sets  the  select_end_x  and 
select_end_y  instance  part  variables  to  reflect  the  bottom-right  corner  of  the  selection, 
and  then  swaps  the  top-left  and  bottom-right  coordinates  if  the  end  coordinate  is  to  the  left  or 
above  the  start  coordinate.  If  the  start  and  end  coordinates  are  the  same,  then  the  action 
returns,  since  no  selection  was  made.  If  a  selection  was  made,  MakeSelection  calls  xt- 
OwnSelection. 


10.2.3    Making  the  Selection  with  XtOwnSelection  (Owner) 

Once  the  area  is  highlighted,  Widget  A  calls  XtOwnSelection  to  assert  that  it  wants  the 
right  to  set  the  value  of  a  property  that  will  be  used  to  transfer  information. 

XtOwnSelection  is  called  with  six  arguments: 

Boolean  XtOwnSelection (widget,  selection,  time,  convert_proc, 

lose_ownershlp_procf  trans fer_done_proc) 
Widget  widget; 
Atom  selection; 
Time  time; 

XtConvertSelectionProc  convert_proc; 
Xt Lose Selection? roc  lose_ownership_proc; 
Xt Select ionDoneP roc  trans fer_done_proc; 

The  selection  argument  specifies  an  Atom — a  number  representing  a  property.  Proper 
ties  are  arbitrarily  named  pieces  of  data  stored  on  the  server.  To  simplify  communication 
with  the  server,  a  property  is  never  referenced  by  name,  but  by  a  unique  integer  ID  called  an 
atom.  Standard  atoms  are  defined  in  <Xatom.h>  using  defined  symbols  beginning  with  XA_; 
nonstandard  atoms  can  be  obtained  from  the  server  by  calling  the  Xlib  function  xt- 
InternAtom. 

Widgets  that  support  one  selection  at  a  time  pass  the  predefined  XA_PRIMARY  atom  to  Xt 
OwnSelection.  The  ICCCM  also  allows  you  to  use  the  XA_SECONDARY  and 
XA_CLIPBOARD  atoms.  XA_SECONDARY  would  be  used  by  widgets  implementing  behavior 
involving  more  than  one  selection  (for  example,  allowing  the  user  to  make  two  selections, 
and  to  exchange  the  data  they  contain).  No  current  clients  implement  this  behavior.  The 
XA_CL  IP  BOARD  atom  should  be  used  by  a  widget  that  allows  the  user  to  delete  a  selection. 
We'll  talk  more  about  the  properties  referenced  by  the  XA_SECONDARY  and  XA_CLIPBOARD 
atoms  in  Section  10.2.9.3. 

The  purpose  of  the  XtOwnSelection  call  is  to  make  sure  that  only  one  widget  has  the 
right  to  set  the  XA_PRIMARY  selection  property  at  a  time,  and  to  assert  that  this  widget  is  pre 
pared  to  honor  requests  for  this  data.  Notice  that  when  you  select  text  with  xterm,  that  text  is 
highlighted  only  until  you  select  a  different  area  in  a  different  window. 


288  X  Toolkit  Intrinsics  Programming  Manual 


The  next  three  arguments  to  xtOwnSelection  specify  procedures  that  will  carry  out 
essential  parts  of  the  selection  operation: 

•  The  convert_proc  is  responsible  for  converting  the  selected  data  into  the  representa 
tion  requested  by  the  requestor  in  its  call  to  xtGetSelectionValue;  this  function 
is  called  by  Xt  when  a  Select  ionRequest  event  arrives.  This  happens  as  a  result  of 
the  requestor  calling  XtGetSelectionValue.   The  convert^proc  is  of  type 
XtConvert Select ionProc. 

•  The  lose_o*rnership_proc  clears  the  highlighted  area  when  this  widget  has  lost 
the  selection  (because  some  other  widget  has  taken  it);  this  routine  is  called  by  Xt  when  a 
SelectionClear  event  arrives.   The  lose_ownership_jproc  is  of  type  xt- 
LoseSelectionProc. 

•  The  trans fer_done_jproc  is  called  by  Xt  when  the  requestor  has  successfully 
retrieved  the  converted  value.   If  this  selection  is  intended  to  be  erased  after  being 
transferred  once,  this  function  should  free  any  storage  allocated  in  the  transfer.   If, 
instead,  the  owner  remains  ready  for  pasting  the  same  selection  into  other  widgets,  this 
function  pointer  should  be  NULL.  (For  example,  xterm  does  not  clear  its  selection  after 
pasting  once.)  The  t  ransfer_done_proc  is  of  type  Xt  Select  ionDoneP  roc. 

The  XtOwnSelection  call  also  takes  a  time  argument — this  should  be  the  time  from 
the  event  that  completed  the  highlighting,  not  the  constant  CurrentTime.  If  XtOwn 
Selection  returns  FALSE,  it  means  that  because  of  network  conditions  another  client  has 
called  XtOwnSelection  with  a  more  recent  time  argument 

XtOwnSelection  returns  TRUE  or  FALSE  to  indicate  whether  Widget  A  has  been  granted 
ownership.  If  TRUE,  and  if  this  widget  was  not  already  the  owner,  then  the  old  owner  (if  any) 
will  receive  a  SelectionClear  event  and  will  clear  its  highlighted  area.  The  process 
may  end  here  if  the  user  never  pastes  the  selected  data  anywhere.  If  the  user  selects  a  differ 
ent  piece  of  data,  the  selection  owner  will  receive  a  SelectionClear  itself  before  ever 
having  converted  the  data  for  a  requestor. 

Otherwise  the  owner  code  waits  to  hear  from  the  requestor  that  it  is  ready  to  paste  the  selec 
tion. 


Requesting  the  Selection  (Requestor) 

When  the  user  pastes  the  selection  into  Widget  5,  Widget  B  becomes  the  requestor  and  the 
second  part  of  the  process  begins.  First  of  all,  Widget  B  needs  a  translation  that  maps  a  cer 
tain  key  or  button  event  to  an  action  that  pastes  data.  This  action  calls  XtGet 
SelectionValue. 

XtGetSelectionValue  is  called  with  six  arguments: 
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void  XtGetSelectionValue  ( widget,  selection,  target,  callback, 

cllent_data,  time) 
Widget  widget; 
Atom  selection; 
Atom  target; 

XtSelectionCallbackProc  callback; 
caddr_t  cllent_data; 
Time  time; 

The  selection  argument  is  an  atom  specifying  which  property  is  being  used  to  transfer 
the  selection.  This  will  typically  be  XA_PRIMARY,  though  in  theory  two  widgets  (or  two 
instances  of  the  same  widget)  could  agree  to  transfer  some  particular  data  using  other  proper 
ties. 

The  target  argument  is  another  atom,  this  one  specifying  a  target  representation  type  in 
which  the  requestor  wants  the  information.  We'll  talk  more  about  the  possible  values  for  this 
atom  in  a  moment. 

The  callback  argument  is  a  pointer  to  a  callback  procedure  that  actually  pastes  the  data. 
Xt  will  call  this  procedure  when  the  owner  has  converted  the  data.  The  XtGet 
SelectionValue  call  registers  the  callback  with  Xt,  and  sends  a  Selection- 
Request  event  to  the  owner. 

When  the  selection  owner  has  successfully  converted  the  data,  the  owner  sends  back  a 
SelectionNotify  event  to  Xt.  Xt  then  calls  the  requestor's  callback  procedure.  The 
callback  procedure  must  handle  the  pasting  of  the  data  into  the  widget's  data  structures,  and 
it  must  handle  the  case  where  the  data  could  not  be  converted  into  the  requested  representa 
tion.  We'll  discuss  the  responsibilities  of  this  procedure  in  more  detail  once  we've  seen  the 
owner's  conversion  procedure. 

The  client_data  argument  of  XGetSelectionValue  is  normally  used  to  pass  the 
event  that  triggered  the  pasting  into  the  requestor  callback.  The  callback  will  use  the  coordi 
nates  at  which  the  event  occurred  as  the  location  at  which  to  paste  the  data. 

As  in  the  call  to  XtOwnSelection,  the  time  argument  should  be  the  time  from  the  event 
that  initiated  the  pasting,  not  the  constant  Cur  rent  Time. 

1 0.2.4.1    Possible  Target  Type  Atoms 

The  target  argument  to  XtGetSelectionValue  is  an  atom  that  the  requestor  uses  to 
tell  the  owner  what  kind  of  information  it  is  looking  for  from  the  selection.*  This  is  not  nec 
essarily  a  conversion  of  the  actual  selection  data.  For  example,  it  might  be  a  timestamp  on 
the  data,  or  some  characteristic  of  it,  such  as  its  size  or  font 

To  take  full  advantage  of  the  Xt  selection  mechanism,  you  need  to  understand  what  atoms 
can  be  used  as  selection  targets.  However,  apart  from  some  standard,  predefined  atoms,  the 
atom  for  a  property  is  not  known  by  a  client  until  it  queries  the  server  for  the  atom  using  an 
xinternAtom  call.  This  call  specifies  the  string  name  of  the  property,  and  returns  the 
atom. 


*  Ai  described  earlier,  atoms  (rather  than  strings)  are  always  used  in  network  transmissions  to  identify  properties. 
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Some  atoms  needed  by  almost  all  applications  are  predefined  in  the  header  file 
<XlllXatom.h>.  These  atoms  are  symbolic  constants  that  can  be  used  without  an 
xinternAtom  call.  The  constants  always  start  with  the  prefix  XA_.  See  <X1 1 IXatom.h> 
for  the  complete  list  of  predefined  atoms. 

Note  that  many  of  the  predefined  atoms  have  uses  in  X  other  than  as  target  types,  and  not  all 
are  appropriate  as  selection  targets.  A  few  of  those  that  might  obviously  be  useful  as  targets 
include: 

XA_STRING 

XA_INTEGER 

XA_BITMAP 

At  present,  the  Athena  widgets  and  the  clients  in  the  MIT  core  X  distribution  use  only 
XA_STRING  as  a  target.  However,  one  can  imagine  uses  for  other  targets  as  well.  For 
example,  XA_FONT  might  be  used  as  a  target  to  indicate  that  the  requestor  doesn't  want  the 
text  of  a  selection,  but  wants  only  to  know  its  font  XA_TIMESTAMP  might  be  used  to  indi 
cate  that  the  requestor  wants  a  timestamp  for  the  data. 

Once  the  xtGetSelectionValue  request  is  made,  a  SelectionRequest  event  is 
generated,  which  Xt  uses  to  invoke  the  owner  widget's  convert_proc.  The 
convert^proc  will  need  to  branch  according  to  the  target  type  passed  in  by  the  requestor 
through  Xt,  and  convert  the  data  accordingly  before  transferring  the  selection  to  the 
requestor. 

For  selection  of  multiple  data  types  to  work  correctly  between  any  two  arbitrarily  chosen 
widgets,  there  must  be  conventions  about  which  targets  will  be  supported.  As  a  step  in  the 
direction  of  interwidget  selection  compatibility,  the  ICCCM  specifies  a  required  target  type  of 
XAJTARGETS,  to  which  the  owner  is  supposed  to  respond  by  returning  a  list  of  the  target 
types  into  which  it  is  capable  of  converting  data.  We'll  talk  about  how  to  work  with  this  tar 
get  in  Section  10.2.9. 

In  a  custom  widget  such  as  BitmapEdit,  which  has  a  custom  data  type  not  represented  by  a 
predefined  atom,  it  is  possible  to  obtain  a  custom  atom  using  XinternAtom,  and  use  that 
as  the  target.  Because  the  XinternAtom  call  requires  a  round  trip  to  the  server,  the  best 
place  to  do  this  is  in  the  widget's  initialize  method.*  The  returned  atom  can  be  stored 
in  a  field  added  to  the  widget's  instance  part.  BitmapEdit's  target  type,  "CELL_ARRAY,"  is 
unique  to  BitmapEdit.  The  atom  is  stored  in  an  instance  part  field  called  target  so  that  it 
is  available  in  convert_proc  and  in  the  requestor  role  code.  Example  10-4  shows  the 
code  added  to  the  initialize  method  to  get  an  atom  for  the  string  "CELL_ARRAY." 

Example  10-4.  BitmapEdit:  getting  the  atom  fora  widget-specific  target  type 

/*  ARGSUSED  */ 

static  void 

Initialize (request,  new) 


'"Since  Xlib  functions  causing  round-trip  requests  can  impact  performance,  they  should  be  called  only  once  if  pos 
sible,  and  where  possible,  during  the  set-up  phase  of  the  application  as  opposed  to  the  event-loop  phase.  If 
XinternAtom  were  called  every  time  the  user  made  a  selection,  it  would  slow  the  application.  In  addition,  since 
atoms  are  server  resources  that  are  not  freed  until  the  server  shuts  down,  it  is  important  to  use  predefined  atoms 
whenever  possible. 
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Example  10-4.  BitmapEdit:  getting  the  atom  fora  widget-specific  target  type  (continued) 
BitmapEditWidget    request,    new; 


new->bitmapEdit .target_atom  =  XInternAtom(XtDisplay (new)  , 
"CELL_ARRAY, "  FALSE); 

The  target  type  property  name  used  by  BitmapEdit  is  "CELL.ARRAY." 

The  third  argument  to  xinternAtom  is  a  Boolean  that  indicates  what  to  do  if  the  atom 
doesn't  already  exist.  If  this  argument  is  TRUE,  XinternAtom  will  return  None.  This 
argument  should  always  be  FALSE  if  you  want  to  create  a  new  atom. 

Note  that  for  repeated  calls  to  xtinternAtom  with  the  same  string  as  an  argument,  even 
from  different  widgets,  the  returned  atom  will  be  the  same.  There  will  be  only  one  atom 
created  for  any  unique  string  interned  on  a  given  server.  (Case  is  important:  "Cell_Array" 
would  return  a  different  atom  than  "CELL_ARRAY".) 

This  XinternAtom  call  occurs  in  every  instance  of  the  BitmapEdit  widget,  since  there  is 
no  way  for  the  widget  instance  to  know  that  other  instances  exist  or  whether  they  have 
already  interned  an  atom.  Both  the  owner  and  requestor  widgets,  in  separate  applications, 
will  get  the  same  atom  in  return. 

10.2.4.2    The  Paste  Action  from  BitmapEdit 

To  initiate  the  requestor  role,  you  need  to  assign  an  event  sequence  to  trigger  the  pasting,  and 
to  write  an  action  that  calls  XtGet  Select ionValue,  and  a  callback  function  that  inserts 
the  returned  data. 

Traditionally  the  action  to  paste  data  is  triggered  by  a  press  of  the  second  pointer  button. 
BitmapEdit  will  use  the  shifted  second  button  since  it  uses  the  unshifted  button  for  other  pur 
poses.  Example  10-5  shows  the  action  mapped  to  Shif  t<Btn2Down>. 

Example  10-5.  BitmapEdit:  action  to  paste  a  selection 

static   void 

PasteSelection (w,  event) 
BitmapEditWidget  w; 
XButtonEvent  *event; 
{ 

XtGetSelectionValue(w,  XA_PRIMARY,  w->bitmapEdit . target_atomr 

requestor_callback,  event, 

event->time) ; 
} 

This  action  can  be  dropped  verbatim  into  your  widget,  replacing  only  the  name  of  the 
instance  fields  you  are  using  to  store  the  target  atom. 
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Converting  the  Selection  (Owner) 

The  real  challenge  in  handling  selections  is  writing  the  convert^proc,  which  converts 
data  to  the  format  specified  by  the  requestor  and  prepares  it  for  transfer. 

As  mentioned  above,  the  widget's  convert^proc  is  called  by  Xt  when  the  requestor  calls 
XtGetSelectionValue.  The  procedure  is  passed  the  selection  atom  and  the  target 
atom,  and  is  expected  to  return  in  its  arguments  the  type,  value,  size,  and  format  of  the 
converted  selection  data. 

To  support  the  possibility  of  having  to  convert  the  data  to  any  one  of  several  targets,  the  code 
branches  according  to  the  value  of  the  target  passed  in,  and  does  its  conversions  accordingly. 
In  the  version  of  BitmapEdit's  convert_proc  shown  here,  only  one  target  type  is 
handled,  but  provision  is  made  for  future  expansion. 

Once  the  conversion  is  made,  the  procedure  sets  the  value_retuz-n  argument  passed  in  to 
a  pointer  to  a  block  of  memory,  and  length_return  to  the  size  of  the  block.  This  block 
of  memory  will  be  set  into  a  property  by  Xt  and  passed  to  the  requestor's  callback  in  the 
same  form — as  a  pointer  to  a  block  of  memory  and  a  length.  This  puts  constraints  on  the  for 
mats  that  can  be  used  for  the  data. 

For  text  selections,  the  data  is  usually  a  simple  character  string.  The  convert_j>roc  sim 
ply  needs  to  set  *value_return  to  a  pointer  to  the  string,  and  length_return  to  the 
length  of  the  string.  For  BitmapEdit,  however,  the  required  data  is  a  string  (of  bitmap  cell 
states)  plus  width  and  height  values.  Since  C  provides  easy  ways  to  put  numeric  values  into 
strings  and  to  get  them  out  again  at  the  other  end,  we've  chosen  to  handle  this  data  by 
converting  the  numbers  to  characters  and  tacking  them  on  to  the  beginning  of  the  string. 

If  your  selection  is  composed  of  a  number  of  numeric  values,  you  can  create  a  structure  con 
taining  the  values  and  then  pass  a  pointer  to  the  structure.  However,  the  structure  cannot 
contain  pointers,  because  the  data  pointed  to  by  these  pointers  will  not  be  set  into  the  selec 
tion  property.  For  example,  BitmapEdit  cannot  pass  a  pointer  to  a  structure  containing  a 
string  pointer  field  and  width  and  height  fields,  because  the  block  of  memory  pointed  to  by 
the  string  pointer  will  not  be  copied. 

In  this  case,  the  type_return  can  simply  be  the  target  atom  that  was  passed  in,  indicating 
that  the  data  is  of  the  requested  type. 

The  f  ormat_return  is  the  size  in  bytes  of  each  element  in  the  array.  Since  we  are  pass 
ing  a  compound  string,  this  value  is  8.  If  we  were  passing  a  structure,  length_return 
would  be  1  and  *f  ormat_return  would  be  8  times  the  size  of  the  structure  in  bytes. 

Example  10-6  shows  BitmapEdit's  convert_proc. 

Example  10-6.  BitmapEdit:  converting  the  selection  value 

static  Boolean 

convert_proc (w,  selection,  target,  type_return,  value_return, 

length_return,  format_return) 
BitmapEditWidget  w; 
Atom  *selection; 
Atom  *target; 
Atom  *type_return; 
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Example  1  0-6.  BitmapEdit:  converting  the  selection  value  (continued) 

caddr_t  *value_return; 
unsigned  long  *length_return; 
int  *f  ormat_return; 
{ 

int  x,  y; 

int  width,  height; 

if  (*target  ==  w->bitmapEdit  .  target_atom)  { 
char  *data; 

width  =  w->bitmapEdit  .  select_end_x  - 

w->bitmapEdit  .  select_start_x; 
height  =  w->bitmapEdit  .  select_end_y  - 

w->bitmapEdit  .  select_start_y  ; 

/*  8  chars  is  enough  for  2  3-digit  numbers  and  2  delimiters  */ 
*length__return  *••  ((width  *  height)  +  8)  *  sizeof  (char)  ; 

data  =  XtMalloc  (*length_return)  ; 
sprintf  (data,  "%d@%d~",  width,  height); 

for  (x  =  0;  x  <  width;  x++)  { 

for  (y  =  0;  y  <  height;  y++)  { 

data  [8  +  x  +  (y  *  width)]  = 

w->bitmapEdit  .cell  [  (x  + 
w->bitmapEdit  .  select_start_x)  + 
(  (y  +  w->bitmapEdit  .  select_start_y)  * 
w->bitmapEdit  .pixmap_width_in_cells)  ]  ; 

} 
i 

*value_return  =  data; 

*type_return  =  w->bitmapEdit  .  target_atom; 

*format_return  =  8; 
return  (TRUE)  ; 


This  code  determines  the  width  and  height  of  the  selected  rectangle  from  the  instance  part 
fields,  and  then  allocates  enough  memory  to  fit  a  character  array  big  enough  to  fit  the  width 
and  height  values,  delimiters,  and  a  width  by  height  character  array.  Then  it  copies  the  cur 
rent  contents  of  the  selected  area  into  the  allocated  character  array.  Finally,  it  sets 
*value_return  to  point  to  the  compound  string,  and  sets  *length_return  to  the 
length  of  this  string.  *f  ormat_return  is  the  size  in  bits  of  each  element  in  the  array, 
which  in  this  case  is  8  bits. 


294  X  Toolkit  Intrinsics  Programming  Manual 


10.2.6   Finally  Pasting  the  Selection  (Requestor) 

When  the  owner's  convert_proc  returns,  Xt  sends  a  SelectionNotif y  event  to  the 
requestor.  The  Xt  code  on  the  requestor  side  then  invokes  the  callback  routine  the  requestor 
registered  with  the  call  to  xtGetSelectionValue. 

The  requestor_callback  function  is  passed  all  the  same  arguments  that  the  owner 
received  in  the  convert_proc,  plus  the  values  that  the  owner  returned  through  the  argu 
ment  of  convert_proc.  In  the  BitmapEdit  widget,  it  sets  instance  part  fields  to  paste  the 
data. 

Example  10-7  shows  the  requestor  callback  function  from  BitmapEdit 
Example  10-7.  BitmapEdit:  pasting  selection  in  requestor_callback  function 

/*  ARGSUSED  */ 

static  void 

requestor_callback (w,  event,  selection,  type,  value,  length,  format) 

BitmapEditWidget  w; 

XButtonEvent  *event;     /*  client_data,  to  pass  press  position  */ 

Atom  *selection; 

Atom  *type; 

caddr_t  value; 

unsigned  long  *length; 

int  * format; 

{ 

if  ((*type  =  07*  XT_CONVERT_FAIL  */)  I  I  (*length  ==0))  { 
XBelKXtDisplay(w)  ,  100); 

fprintf (stderr,  "bitmapEdit :  no  selection  or  selection\ 
timed  out;  try  again\n"); 

} 
else  { 

int  width,  height; 

int  x,  y; 

int  dst_offset_x,  dst_of f set_y; 

char  *ptr; 

/*  figure  pointer  position  in  cells  */ 
dst_offset_x  = 

(w->bitmapEdit .cur_x  +  event->x)  / 
w->bitmapEdit .cell_size_in_pixels; 
dst_offset_y  = 

(w->bitmapEdit .cur_y  +  event->y)  / 

w->bitmapEdit .cell_size_in_pixels; 

. 

/*  extract  width  and  height  from  string  */ 

ptr  =  value; 

width  =  atoi (ptr) ; 

ptr  =  index (ptr,  '@'); 

ptr++; 

height  =  atoi (ptr) ; 

/*  set  ptr  to  beginning  of  char  array.  */ 
ptr  =  & value [8] ; 

/*  copy  char  array  into  widget  cell  array, 

*  checking  ranges  as  necessary,  and  draw 

*  cells  that  change  into  pixmap.  */ 


oat: 
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Example  10-7.  BitmapEdit:  pasting  selection  in  requestor_callback  function  (continued) 

•  >-:•!::•: 

for  (x  =  0;  x  <  width;  x++)  { 

for  (y  =  0;  y  <  height;  y++)  { 

/*  range  checking  */ 

if  (  (  (dst_of  f  set_x  +  x)  > 

w->bitmapEdit  .pixmap_width_in_cells) 
II  (  (dst_of  f  set_x  +  x)  <  0)) 
break; 
if  (  (  (dst_offset_y  -f  y)  > 

w->bitmapEdit  .pixmap_height_in_cells) 
II  (  (dst_of  fset_y  +  y)  <  0)  ) 
break; 

/*  setting  cell  array  */ 

w->bitmapEdit  .cell  [  (dst_of  f  set_x  +  x)  + 
(  (dst_offset_y  +  y)  *  ~ 
w->bitmapEdit  .pixmap_width_in_cells)  ] 
=  ptr[x  +  (y  *  width)]; 

/*  updating  pixmap  */ 

if  (w->bitmapEdit  .cell  [  (dst_of  f  set_x  +  x)  + 
(  (dst_offset_y  +  y)  * 

w->bitmapEdit  .pixmap_width_in_cells)  ] 
==  DRAWN) 

DrawCell  (w,  dst_of  f  set_x  +  x,  dst_of  f  set_y  +  y, 

w->bitmapEdit  .  draw_gc)  ; 
else 

DrawCell  (w,  dst_of  f  set_x  +  "x,  dst_of  f  set_y  +  y, 
w->bitmapEdit  .undraw_gc)  ; 


/*  the  requestor  must  free  the  data  passed  by 

*  Xt  after  using  it.  */ 
XtFree  (value)  ; 

/*  copy  updated  pixmap  to  window  */ 
Redisplay  (w,  NULL)  ; 


The  requestor_callback  first  determines  whether  the  conversion  was  a  success  by 
checking  the  target  type  and  data  length.  If  it  was  not,  it  beeps  and  possibly  prints  a  message. 
This  can  happen  if  no  selection  has  been  made,  or  if  there  is  some  delay  that  causes  the  selec 
tion  to  have  timed  out  before  the  owner  could  convert  the  data. 

If  the  conversion  was  a  success,  the  requestor_callback  pastes  the  data.  In  Bitmap- 
Edit'  s  case,  the  requestor  must  first  convert  the  data  into  a  more  useful  form.  This  means 
extracting  the  width  and  height  values,  and  then  setting  the  widget's  cell  array  based  on  the 
data  in  the  character  array  passed  in.  Note  that  the  code  should  check  to  make  sure  that  the 
data  can  be  pasted  in  the  desired  position.  BitmapEdit  must  make  sure  that  no  attempt  is 
made  to  set  a  cell  array  member  outside  of  the  bitmap.  The  routine  then  updates  the  screen 
display  of  the  widget. 
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The  final  responsibility  of  the  request  or_callback  is  to  free  the  memory  passed  in  by 
Xt. 


If  the  Selection  is  Lost  (Owner) 

If  the  owner  loses  the  selection,  either  because  the  selection  timed  out  or  because  the  user 
made  a  different  selection,  the  lose_ownership_proc  that  was  registered  with  its  call 
to  XtOwnSelection  will  be  invoked.  Typically,  this  function  simply  clears  any  high 
lighting  or  other  visual  feedback  about  the  selection,  and  resets  to  their  initial  state  any  inter 
nal  variables  used  in  handling  selections. 

Example  10-8  shows  the  lose_ownership_proc  from  the  BitmapEdit  widget 
Example  10-8.  BitmapEdit:  the  bse_ownership_proc 

/*  ARGSUSED  */ 

static  void 

lose_ownership_proc (w,  selection) 

BitmapEditWidget  w; 

Atom  *selection; 

{ 

/*  clear  old  selection  */ 

w->bitmapEdit . f irst_box  =  FALSE; 

w->bitmapEdit . select_start_x  =  0; 

w->bitmapEdit . select_start_y  =  0; 

w->bitmapEdit . select_end_x  =0; 

w->bitmapEdit . select_end_y  =  0; 

Redisplay (w,  NULL); 


When  the  Selection  Transfer  is  Complete  (Owner) 

The  transfer_done_j>roc,  registered  in  the  call  to  XtOwnSelection,  is  called 
when  the  transfer  is  complete.  It's  job  is  to  do  any  processing  necessary  to  get  ready  for  the 
next  selection  request  In  many  cases  no  processing  is  necessary  and  this  function  can  be 
NULL  in  the  call  to  XtOwnSelection.  However,  this  function  might  clear  variables  or 
free  memory.  Some  transfers  are  intended  to  be  made  only  once,  to  make  sure  that  there  is  no 
duplication  of  information.  In  these  cases,  the  transfer_done_proc  would  do  a  lot 
more,  including  erasing  the  visual  selection,  calling  xtDisownSelection  (and  perhaps 
even  erasing  the  data  that  was  selected). 
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10.2.9   ICCCM  Compliance 

For  any  two  widgets  to  be  able  to  transparently  transfer  different  types  of  data,  there  must  be 
agreement  about  the  possible  target  types  and  their  contents.  The  ICCCM  suggests  a  list  of 
possible  target  types,  as  shown  in  Table  10-2.  If  you  can,  use  one  of  these  target  types  since 
this  will  increase  the  chances  that  your  widget  will  be  able  to  communicate  with  widgets 
written  by  other  people. 


Table  10-2.  Target  Types  Suggested  in  ICCCM 


Atom 


TARGETS 

MULTIPLE 

TIMESTAMP 

STRING 

TEXT 

LIST_LENGTH 

PKMAP 

DRAWABLE 

BITMAP 

FOREGROUND 

BACKGROUND 

COLORMAP 

ODIF 

OWNER_OS 

FILE.NAME 

HOSTJSTAME 

CHARACTER_POSmON 

LINE_NUMBER 

COLUMN_NUMBER 

LENGTH 

USER 

PROCEDURE 

MODULE 

PROCESS 

TASK 

CLASS 

NAME 

CUENT.WINDOW 

DELETE 

INSERT_SELECnON 

INSERT  PROPERTY 


Type 


ATOM 

ATOM_PAIR 

INTEGER 

STRING 

TEXT 

INTEGER 

DRAWABLE 

DRAWABLE 

BITMAP 

PIXEL 

PIXEL 

COLORMAP 

TEXT 

TEXT 

TEXT 

TEXT 

SPAN 

SPAN 

SPAN 

INTEGER 

TEXT 

TEXT 

TEXT 

INTEGER,  TEXT 

INTEGER,  TEXT 

TEXT 

TEXT 

WINDOW 

NULL 

NULL 

NULL 


Meaning 


List  of  valid  target  atoms 

Look  in  the  ConvertSelection  property 

Timestamp  used  to  acquire  selection 

ISO  Latin  1  (+TAB+NEWLINE)  text 

Text  in  owner's  encoding 

Number  of  disjoint  parts  of  selection 

Pixmap  ID 

Drawable  ID 

Bitmap  ID 

Pixel  value 

Pixel  value 

Colormap  ID 

ISO  Office  Document  Interchange  Format 

Operating  system  of  owner 

Full  path  name  of  a  file 

See  WM_CLIENT_MACHINE 

Stan  and  end  of  selection  in  bytes 

Stan  and  end  line  numbers 

Stan  and  end  column  numbers 

Number  of  bytes  in  selection 

Name  of  user  running  owner 

Name  of  selected  procedure 

Name  of  selected  module 

Process  ID  of  owner 

Task  ID  of  owner 

Class  of  owner — see  WM_CLASS 

Name  of  owner — see  WM_NAME 

Top-level  window  of  owner 

TRUE  if  owner  deleted  selection 

Insert  specified  selection 

Insert  specified  property 


More  entries  are  expected  to  be  added. 
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Because  not  every  widget  will  support  every  possible  target  type,  the  ICCCM  specifies  a  tar 
get  type  of  XA_TARGETS,  to  which  the  owner  is  required  to  respond  by  returning  a  list  of  the 
target  types  into  which  it  is  capable  of  converting  data. 

Normally,  a  requestor  would  first  call  xtGet Select ionValue  for  XAJTARGETS,  and 
then,  in  the  callback,  determine  which  target  it  wants  to  request  from  the  list,  and  then  call 
xtGetSelectionValue  again  for  the  desired  target  with  a  separate  callback  to  process 
the  actual  data.  This  is  really  two  separate  selection  transfers. 

In  Release  3,  though,  XA_TARGETS  itself  is  not  yet  implemented  as  a  predefined  atom.  To 
use  it,  you  must  use  the  Xmu  atom  caching  mechanism  described  in  Section  10.2.9.1. 

Fortunately,  there  is  existing  template  code  that  you  can  copy  to  handle  XA_TARGETS  and 
some  other  standard  target  types  that  are  required  by  the  ICCCM. 

This  template  code  uses  the  Xmu  routine  XmuConvertStandardSelection.  It  also 
uses  an  Xmu  atom-caching  facility  that  eliminates  the  need  for  xinternAtom  calls  for 
each  of  the  ICCCM  standard  target  atoms.* 

Xmu  Atom  Caching 

Xmu's  caching  facility  uses  symbols  similar  to  those  defined  in  <XlllXatom.h>,  only  in  this 
case,  they  are  macros  that  take  an  argument  and  call  XmulnternAtom,  For  example,  the 
macro  for  XAJTARGETS  is  defined  as  follows  in  <XlllXmu.h>: 

fdefine  XAJTARGETS (d)       XmulnternAtom (d,  _XA_TARGETS) 

where  d  refers  to  a  pointer  to  a  Display  structure.  (This  can  be  returned  by  the  xt- 
Di splay  macro.)  The  XmulnternAtom  function  first  tries  to  get  the  atom  for  the  string 
"XAJTARGETS"  from  Xmu's  internal  cache.  If  Xmu  doesn't  yet  have  a  value  for  the  atom,  it 
calls  XinternAtom  to  make  a  server  request  Because  this  facility  makes  only  one  query 
to  the  server,  you  can  access  the  atoms  in  this  way  every  time  a  selection  is  made  without  sig 
nificant  penalty.  This  allows  you  to  place  the  XA_TARGETS  ( )  macro  in  your  selection 
code  instead  of  adding  an  instance  part  variable  and  setting  itintheinitialize  method. 

You  might  use  this  macro  as  follows  in  a  convert_proc  branch  dedicated  to  handling  the 
TARGETS  target  type: 

if    (*target   ==   XA_TARGETS (XtDisplay (w) ) )     {     ... 

The  Xmu  atom  caching  mechanism  must  be  initialized  before  you  can  make  calls  of  the  form 
just  shown.  Example  10-9  shows  the  code  that  should  be  placed  in  the  widget's 
initialize  method  to  initialize  this  mechanism. 


'"Since  the  adoption  of  the  ICCCM  as  an  X  Consortium  standard  occurred  fairly  recently,  the  list  of  atoms  supported 
by  the  Xmu  atom  caching  mechanism  may  change  radically.  For  example,  in  Release  3,  neither  XAJTARGETS  nor 
XA_CLIPBOARD  is  defined  as  a  predefined  atom,  even  though  they  are  required  by  the  ICCCM.  See  <Xll/Xmu.h> 
under  Release  3  or  <Xll/XmuJ Atoms. h>  under  Release  4  for  the  list  of  predefined  atoms  on  your  system. 
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Example  10-9.  BitmapEdit:  initializing  Xmu's  atom  caching  m&chanism  in  the  initialize  method 

(void)  XmuInternAtom(  XtDisplay (new) ,  XmuMakeAtom(nNULL")  ); 


10.2.9.2    Converting  the  Standard  Selections 

The  Xmu  routine  XmuConvertStandardSelection  can  be  used  to  respond  to  a 
TARGETS  selection  request,  as  well  as  to  other  standard  targets  denned  by  Xmu. 

Example  10-10  shows  the  portion  of  the  convert_proc  for  BitmapEdit  that  handles  the 
standard  targets. 

This  code  is  adapted  from  the  standard  client  xclipboard,  and  can  be  copied  almost  directly 
into  your  widget 

Example  10-10.  BitmapEdit:  converting  standard  targets  in  the  convert_proc 

static  Boolean 

convert_proc (w,  selection,  target,  type_return,  value_return, 

length_return,  format_return) 
!p   BitmapEditWidget  w; 
Atom  *selection; 
Atom  * target; 
Atom  *type_return; 
caddr_t  *value_return; 
unsigned  long  *length_return; 
int  *format_return; 

int  x,  y; 

int  width,  height; 

/*  handle  TARGETS  target  */ 
if  (*target  ==  XAJTARGETS (XtDisplay (w) ))  { 
Atom*  targetP; 
Atom*  std_targets; 
unsigned  long  std_length; 

XmuConvertStandardSelection (w,  CurrentTime,  selection, 
target,  type_return, 
(caddr_t*) &std_targets, 
&std_length,  format_return) ; 

*value_return  =  XtMalloc (sizeof (Atom) * (std_length  +  1)); 
targetP  =  * (Atom**) value_return; 
*length_return  =  std_length  +  1; 
*targetP++  =  w->bitmapEdit .target_atom; 
bcopy ( (char*) std_targets,  (char*) targetP, 

sizeof (Atom) *std_length) ; 
XtFree ( (char*) std_targets)  ; 
*type_return  =  XA_ATOM; 
*format_return  =  sizeof (Atom)  *  8; 
ret urn (TRUE) ; 


/*  Xt  already  handles  MULTIPLE,  no  branch  needed  */ 

/*  Handle  expected  selection  target  */ 

else  if  (*target  ==  w->bitmapEdit . target_atom)  { 

/*  code  shown  and  described  earlier  in  text  */ 
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Example  10-10.  BitmapEdit:  converting  standard  targets  in  the  convert_proc  (continued) 


else  { 

/*  Handle  other  standard  targets  defined  by  Xmu  */ 
if  (XmuConvertStandardSelection(w,  CurrentTime, 

selection,  tarrget,  type_return, 
value_return,  length_return, 
forma t_return) ) 
return  TRUE; 
else  { 

fprintf (stderr,  "bitmapEdit :  requestor  is  requesting", 

"unsupported  selection  target  type.Xn") 
return (FALSE) ; 


Overall,  this  code  handles  the  TARGETS  atom  in  the  first  branch,  the  expected  selection  target 
in  the  second,  and  any  remaining  standard  atoms  and  any  unknown  atoms  as  two  cases  in  the 
third  branch.  For  ICCCM-compliant  code,  you  can  copy  this  entire  function  into  your  widget 
and  then  write  just  the  second  branch.  Note  that  branches  that  successfully  provide  the 
requested  data  return  TRUE,  and  ones  that  don't  return  FALSE.* 

In  the  first  branch  you  will  also  need  to  change  the  reference  to  the  instance  part  field  that 
stores  the  target  atom  used  for  selections,  bitmapEdit .  target_atom.  If  your  widget 
uses  a  predefined  atom  or  one  supported  by  the  Xmu  facility,  you  would  reference  that  atom 
here  instead  of  the  instance  part  field.  If  you  called  xinternAtom  in  initialize  and 
stored  the  result  in  an  instance  part  field,  you  specify  that  here. 

10.2.9.3    The  Clipboard  Selection 

According  to  the  ICCCM,  if  a  widget  or  application  allows  the  user  to  delete  a  selection,  the 
selection  owner  code  should  place  the  deleted  data  on  the  CLIPBOARD  selection.!  The  wid 
get  should  be  prepared  to  respond  to  a  request  for  the  contents  of  the  CLIPBOARD,  much  as 
it  does  for  the  PRIMARY  selection.  The  only  client  that  requests  data  in  this  way  will  be 
xclipboord. 

Except  when  a  widget  asserts  ownership  of  the  CLIPBOARD  with  XtOwnSelection  in 
order  to  place  newly  deleted  data  on  it,  the  xdipboard  client  is  the  owner  of  this  property. 
When  it  starts  up,  xdipboard  asserts  ownership  of  the  CLIPBOARD  selection.  If  it  loses  the 
selection  (which  will  happen  whenever  a  widget  or  client  has  newly  deleted  the  contents  of  a 


*The  ICCCM  also  specifies  that  functions  implementing  selections  must  be  able  to  respond  to  a  MULTIPLE  target  val 
ue,  which  is  used  to  handle  selections  too  large  to  fit  into  a  single  property.  However,  the  necessary  handling  is  done 
by  the  Intrinsics.  Your  procedures  do  not  need  to  worry  about  responding  to  the  MULTIPLE  target  value;  a  selection 
request  with  this  target  type  will  be  transparently  transformed  into  a  series  of  smaller  transfers. 
fAs  mentioned  earlier,  XA_CLIPBOARD  is  not  a  predefined  atom,  and  must  be  handled  via  the  Xmu  atom  caching 
mechanism  or  equivalent  code. 
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selection),  it  obtains  the  contents  of  the  selection  from  the  new  owner,  then  reasserts  its  own 
ownership  of  the  selection. 

Clients  wishing  to  restore  deleted  data  should  request  the  contents  of  the  CLIPBOARD, 
using  the  same  techniques  as  we've  shown  for  the  PRIMARY  selection,  xclipboard  will 
respond  to  these  requests,  returning  the  deleted  data. 

The  use  of  xclipboard  allows  the  value  of  a  selection  to  survive  the  termination  of  the  origi 
nal  selection  owner. 


10.2.10   Miscellaneous  Selection  Routines 

If  the  user  deletes  the  information  selected,  the  owner  should  call  XtDisownSelection. 
If  the  trans fer_done_jproc  is  used  because  the  selection  is  intended  to  be  made  only 
once,  it  should  call  XtDisownSelection,  as  well  as  erasing  the  highlighting  of  the  visi 
ble  selection. 

xtSetSelectionTimeout  sets  the  time  within  which  widgets  must  respond  to  one 
another.  This  is  initially  set  by  the  XtNselectionTimeout  resource,  and  defaults  to  5 
seconds.  This  prevents  hanging  when  the  user  pastes  but  the  current  owner  is  slow  or  hung. 
xtGetSelectionTimeout  reads  the  current  selection  timeout  value.  Widgets  should 
not  normally  require  these  two  calls,  since  the  selection  timeout  should  remain  under  the 
user's  control. 

If  the  requestor  can  request  more  than  one  target  type,  such  as  TARGETS  and  its  normal  selec 
tion  target,  it  normally  does  so  using  separate  actions.  (Both  actions  can  be  invoked  by  the 
same  triggering  event,  if  desired.)  Each  action  specifies  a  different  target  type  and  a  different 
requestor  callback.  That  way,  each  requestor  callback  handles  only  one  type  of  target. 

Beware:  there  is  a  danger  in  this  approach.  There  is  a  chance  that  the  selection  owner  might 
change  between  the  repeated  XtGetSelectionValue  calls.  XtGetSelection- 
vaiues  (plural)  can  be  used  instead  if  the  requestor  would  like  to  receive  the  data  in  more 
than  one  representation.  The  requestor's  single  callback  function  would  then  be  called  once 
for  each  representation.  (The  owner's  convert_proc  would  also  be  called  once  per  rep 
resentation.) 
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Geometry  Management 


This  chapter  discusses  how  composite  and  constraint  widgets  manage  the 
layout  of  widgets,  and  how  to  write  your  own  simple  composite  and  constraint 
widgets. 
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Composite  and  constraint  widgets  lay  out  the  widgets  in  your  application  according  to  certain 
rules.  You  cannot  hardcode  the  position  of  widgets  in  an  application  because  X  applications 
can  be  resized  and  they  must  reposition  their  widgets  to  take  advantage  of  the  available 
space.  Because  of  the  window  manager,  even  the  initial  size  of  the  application  may  not  be 
the  application's  preferred  size. 

Chapter  3,  More  Widget  Programming  Techniques,  demonstrated  how  you  can  use  existing 
composite  and  constraint  widgets  in  the  application.  You  can  control  widget  layout  rules 
with  resources.  However,  you  may  find  that  no  existing  composite  or  constraint  widget  can 
be  configured  with  resources  to  have  the  layout  rules  you  need.  In  this  case,  you  will  need  to 
write  your  own  composite  or  constraint  widget,  or  modify  an  existing  one.  However,  before 
embarking  on  writing  one  of  these  widgets,  you  should  realize  that  composite  and  constraint 
widgets  are  complex.  First  investigate  the  alternatives!  Perhaps  you  can  find  a  composite  or 
constraint  widget  from  another  widget  set  that  has  the  layout  characteristics  you  need.  If  you 
determine  that  you  have  no  alternative  but  to  write  your  own  composite  or  constraint  widget, 
you  should  keep  it  as  simple  as  possible.  It  is  much  easier  to  write  a  special-purpose  widget 
that  handles  a  limited  layout  situation  than  it  is  to  write  a  general-purpose  composite  or  con 
straint  widget  like  Box  or  Form.  And  even  Box  and  Form  are  simple  as  composite  and  con 
straint  widgets  go! 

A  composite  widget  is  defined  as  any  widget  that  is  a  subclass  of  the  Xt-defmed  class  Com 
posite.  A  constraint  widget  is  any  widget  that  is  a  subclass  of  the  Xt  defined  class  Con 
straint  Constraint  is  a  subclass  of  Composite.  As  you  may  recall,  a  composite  widget  is  the 
simplest  kind  of  geometry-managing  widget;  it  handles  all  its  children  equally,  or  handles 
each  child  in  a  fixed  way.  For  example,  the  Box  widget  handles  all  of  its  children  equally. 
As  an  example  of  a  special-purpose  composite  widget,  Section  11.2  describes  a  composite 
widget  called  ScrollBox  that  manages  two  scrollbars  and  a  main  window.  This  widget 
requires  that  it  have  exactly  three  children  added  in  a  particular  order. 

A  constraint  widget  has  all  the  characteristics  of  composite  widgets,  but  maintains  configur 
able  data  about  each  child  so  that  it  can  cater  to  the  needs  of  each  child.  By  setting  the  con 
straint  resources  of  a  child  of  a  constraint  widget,  you  configure  the  constraint  widget's  lay 
out  policy  for  that  child.  Constraint  widgets  are  inherently  more  powerful  than  composite 
widgets,  but  also  more  complicated  to  write.  A  constraint  widget  requires  all  the  code  of  a 
composite  widget,  plus  code  to  handle  the  constraints  of  each  child.  Because  of  this  com 
plexity,  you  should  hesitate  even  further  before  attempting  to  write  a  constraint  widget.  As 
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an  example  of  the  code  for  a  constraint  widget,  this  section  describes  the  Athena  Form 
widget 

Composite  and  constraint  widgets  can  be  used  within  widgets  as  well  as  within  applications. 
For  example,  you  may  recall  that  the  xbitmap  application  was  implemented  using  the 
BitmapEdit  widget  and  adding  scrollbars  from  the  application.  We  could  rewrite  the  Bitmap- 
Edit  widget  to  provide  its  own  scrollbars,  controllable  through  resources.  This  widget  would 
create  a  composite  widget  and  three  children;  BitmapEdit  and  two  Scroll  widgets.  This  kind 
of  compound  widget  is  actually  made  up  of  several  widgets,  but  to  the  application  writer  it 
should  act  like  a  single  widget  The  advantage  of  this  rewrite  would  be  that  the  application 
code  would  become  simpler,  and  the  bitmap  editor  with  scrollbars  could  be  easily  used  in 
other  applications.  The  fourth  major  section  of  this  chapter  describes  how  to  write  a  com 
pound  widget 

It  is  a  good  idea  to  define  exactly  what  is  meant  by  the  geometry  of  a  widget.  The  geometry 
of  a  widget  is  its  position,  its  size,  and  its  border  width.  These  are  the  Core  fields  x,  y, 
width,  height,  and  border_width.  Border  width  is  included  because  window  posi 
tions  are  measured  from  the  origin  of  the  parent  (the  top-left  corner  inside  the  border  of  the 
parent)  to  the  top-left  corner  outside  the  border  of  the  child.  Therefore,  changing  the  border 
width  of  a  widget  by  1  pixel  moves  the  origin  of  that  widget  1  pixel  along  both  the  x  and  y 
axes  relative  to  its  parent.  This  concept  is  shown  in  Figure  11-1. 

Geometry  management  may  also  control  the  stacking  order  of  a  group  of  children  (that  is, 
which  children  appear  to  be  on  top).  However,  control  of  the  stacking  order  is  more  manual 
than  control  of  geometry,  because  it  isn't  completely  built  into  Xt. 


11.1   How  Composite  Management  Works 

Like  simple  widgets,  the  characteristics  of  a  composite  widgets  are  defined  by  their  methods. 
The  key  methods  in  a  composite  widget  are  the  Core  methods  resize  and 
query_geometry  and  the  Composite  methods  geometry_manager  and 
change_managed.  We  will  discuss  these  methods  first,  and  then  move  on  to  the  other 
methods  defined  by  Composite,  insert_child  and  delete_child,  which  are  infre 
quently  used. 

We'll  begin  with  a  summary  of  what  these  four  most  important  methods  do.  In  short,  they 
handle  interactions  with  the  three  generations  of  widgets  involved  in  direct  geometry  interac 
tions  with  a  composite  widget;  the  parent  of  the  composite  widget  the  composite  widget 
itself,  and  the  children  of  the  composite  widget 

•  The  resize  method  moves  and  resizes  the  child  widgets  as  necessary  to  fit  within  the 
composite  widget's  new  size. 

•  The  query_geometry  method  supplies  a  preferred  geometry  to  a  widget's  parent 
when  the  parent  calls  xtQueryGeometry.  The  parent  makes  this  call  in  the  process 
of  determining  a  new  layout  for  its  children. 

•  The  geometry_manager  method  handles  resize  requests  from  the  child  widgets. 
Usually,  the  only  kind  of  child  that  will  make  a  resize  request  to  the  parent  is  another 
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Figure  11-1.  Role  of  border  width  in  widget  geometry 

composite  or  constraint  widget  However,  some  simple  widgets  do  request  resizing.  For 
example,  when  a  Label  widget's  string  is  changed  through  resources,  the  Label  widget 
increases  its  own  size  (this  is  allowed  only  in  the  set_values  method).  Xt  then  calls 
the  parent's  geometry_manager  method,  which  must  decide  whether  this  new  size  is 
acceptable  and  then  make  any  changes.  When  a  child  widget  asks  for  more  space  and  the 
composite  widget  doesn't  have  enough,  the  composite  widget's  geometry_manager 
may  ask  its  own  parent  for  more  space  by  calling  XtMakeGeometryRequest. 

•  The  change_managed  method  changes  the  layout  of  the  children  when  a  child  is 
managed  or  unmanaged.  This  occurs  initially  when  xtRealizeWidget  is  called 
(after  children  are  created  with  XtCreateManagedWidget)  or  when  xtManage- 
Child  or  xtManageChildren  is  called  to  add  an  already-realized  widget  to  a  com 
posite  parent's  managed  set  (A  widget  can  be  unmanaged  later  to  remove  it  from  the 
screen  without  destroying  it,  and  managed  again  at  any  time.  Each  time  a  child  is  man 
aged  or  unmanaged,  or  destroyed,  the  change_managed  method  is  called.) 

The  resize  and  query_geometry  methods  were  already  introduced  in  Chapter  6, 
Basic  Widget  Methods,  as  they  apply  in  simple  widgets.  In  composite  widgets,  they  have  the 
same  job,  but  it  is  more  complicated  because  they  now  have  children  to  worry  about.  We  will 
discuss  these  methods  again  in  this  chapter  as  they  appear  in  composite  widgets. 
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To  write  any  of  these  four  methods,  you  need  to  look  at  all  the  ways  that  geometry  changes 
can  occur,  so  that  you  know  all  the  situations  in  which  the  methods  will  be  called.  The  first 
situation  is  the  negotiation  that  takes  place  to  determine  the  initial  size  of  each  widget  when 
an  application  starts  up.  Other  situations  include  when  the  user  resizes  the  entire  application, 
when  a  widget  requests  a  size  change  from  the  application,  and  when  a  widget  is  resized  by 
the  application.  As  you  can  see,  there  are  many  cases.  It  helps  to  be  systematic  about  under 
standing  and  programming  for  these  cases.  The  next  four  sections  describe  each  of  these 
cases  one  at  a  time. 

The  complexity  of  the  geometry  negotiations  in  the  following  description  may  be  intimidat 
ing.  A  truly  general-purpose  composite  widget  is  a  large,  complex  piece  of  software.  You 
should  leave  this  programming  to  the  widget  writers  that  write  commercial  widget  sets,  and 
concentrate  on  things  that  are  more  important  in  your  application.  The  purpose  of  this 
description  is  to  let  you  understand  how  complete  composite  widgets  work,  not  to  suggest 
that  you  should  try  to  write  one.  However,  it  is  possible  to  write  small,  special-purpose  com 
posite  widgets  that  solve  particular  layout  problems.  Composite  widgets  are  simpler  when 
they  are  more  authoritarian — when  they  don't  do  as  much  to  try  to  satisfy  the  preferences  of 
their  children.  Section  11.2  describes  ScrollBox,  a  simple  composite  widget  designed  solely 
to  manage  a  main  widget  and  two  scrollbars.  Writing  this  kind  of  widget  is  manageable 
because  the  widget  manages  a  fixed  number  of  children,  and  has  simple  layout  rules. 

11.1.1    Initial  Geometry  Negotiation 

At  least  one  geometry  negotiation  takes  place  in  any  application,  even  if  the  application  is 
never  resized.  This  occurs  when  an  application  starts  up. 

Figure  11-2  shows  the  process  of  initial  geometry  negotiation  in  schematic  form. 

The  call  to  xtRealizeWidget  initiates  a  two-step  process.  When  xtRealizeWidget 
is  called  on  the  top-level  widget,  most  or  all  of  the  widgets  have  been  created  but  windows 
have  not  been  created  for  them.  XtRealizeWidget  initiates  a  geometry  negotiation  that 
ripples  through  the  widget  hierarchy  (as  is  described  below).  The  widgets'  realize  meth 
ods  (which  create  windows  for  the  widgets)  are  not  called  until  this  process  is  complete. 

XtRealizeWidget  first  calls  the  change_managed  method  of  every  composite 
widget  in  the  application,  beginning  with  the  lowest  widgets  in  the  hierarchy  (called  a  post- 
order  traversal).  Each  change_managed  method  determines  an  initial  size  for  each  child 
and  calls  xtMoveWidget  and/or  xtResizeWidget  for  the  child.  All  the 
change_managed  methods  are  called  until  the  one  in  the  Shell  widget  (Remember  that 
the  Shell  widget  is  a  composite  widget  that  has  only  one  child.)  The  child  is  also  a  composite 
widget  (except  in  single-widget  applications  such  as  xhello).  When  the  Shell  widget  is 
reached,  the  Shell  widget  size  is  set  to  the  size  of  its  child  and  the  process  stops  unless  the 
user  has  specified  an  initial  geometry  for  the  entire  application  through  the  resource  database 
or  command  line. 

A  change_managed  method  can  (but  is  not  required  to)  determine  each  of  its  children's 
preferred  geometry  by  calling  xtQueryGeometry  for  each  child.  This  may  result  in  the 
resize  method  of  the  child  being  called.  Instead  of  calling  XtQueryGeometry,  the 
change_managed  method  may  use  the  child's  Core  width  and  height  fields. 


308  X  Toolkit  Intrinsics  Programming  Manual 


change_managed  method  called  from  bottom  up 


Figure  1 1-2.  Initial  geometry  negotiation,  assuming  sufficient  shell  space 

The  change_managed  method  does  not  determine  the  composite  widget's  own  size.  That 
job  is  for  the  parent  of  the  composite  widget,  which  is  another  composite  widget 

If  the  user-specified,  top-level  widget  geometry  is  different  from  the  geometry  of  the  Shell 
widget's  child  after  all  the  change_managed  methods  are  called,  then  the  Shell  widget 
resizes  its  child  to  the  user-specified  size.  This  makes  Xt  call  the  resize  method  of  the 
child  composite,  and  this  resize  method  reconsiders  the  layout  of  its  children.  This  pro 
cess  proceeds  down  the  chain  of  widgets  to  the  bottom.  At  each  stage  the  resize  method 
can  (but  need  not)  call  xtQueryGeometry  for  each  child  to  get  each  child's  opinion  of 
the  intended  geometry  for  that  child. 

Figure  11-3  shows  the  continued  process  of  initial  geometry  negotiation  if  the  user  has  speci 
fied  the  top-level  geometry  through  resources  rather  than  accepting  the  application's  built-in 
defaults. 

Note  that  this  process  and  the  methods  involved  are  more  complicated  if  the 
change_managed  or  resize  methods  call  XtQueryGeometry.  XtQuery 
Geometry  calls  a  child  widget's  query_geometry  method,  as  described  in  Section  6.6. 
When  they  do  call  XtQueryGeometry,  the  change_managed  or  resize  methods 
need  to  determine  a  suggestion  for  the  child's  geometry,  make  the  XtQueryGeometry 
call,  and  then  do  different  things  depending  upon  which  of  the  three  different  answers  it 
receives  from  the  child.  The  xtGeometryAlmost  answer  includes  a  suggested  compro 
mise.  The  change_managed  or  resize  method  will  decide  on  a  new  size  based  on  the 
compromise,  and  may  or  may  not  make  another  XtQueryGeometry  call  to  make  this 
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If  user  specifies  shell  geometry, 


resize 


methods  called  from  top  down 


Figure  1 1-3.  Initial  geometry  negotiation,  if  resizing  is  necessary 

suggestion  to  the  child.  The  code  to  perform  all  of  this  is  extensive  because  the  suggestions 
and  answers  are  in  the  form  of  structures  with  several  fields.  Only  the  VPaned  (Paned  in 
Release  4)  and  Viewport  classes  in  the  Athena  set  call  xtQueryGeometry,  and  they  do  so 
only  in  minimal  ways.  VPaned  takes  the  height  of  a  pane  from  the  height  returned  by  the 
child  query,  but  only  if  the  child  returns  XtGeometryAlmost.  Since  Viewport  manages 
only  one  child  (in  addition  to  the  scrollbar  widgets  it  creates),  it  queries  that  child  for  its 
geometry  in  its  own  query_geometry  method  (called  when  queried  by  its  parent),  and  in 
its  resize  method. 

Notice  that  this  process  can  result  in  the  resize,  change_managed,  and  possibly  the 
query_geometry  methods  of  every  widget  being  called,  but  the  geometry_manager 
method  does  not  play  a  part. 

Once  this  process  is  complete,  xtRealizeWidget  calls  the  realize  methods  of  all  the 
widgets  and  actually  creates  windows  for  them.  Up  to  this  point,  all  the  methods  were  simply 
changing  the  widget  size  and  position  parameters  in  Xt  structures,  not  the  sizes  of  actual  win 
dows.  XtRealizeWidget  also  maps  all  managed  widgets. 
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11 .1 .2  User  Resizes  the  Application 

When  xtRealizeWidget  returns,  most  applications  call  xtMainLoop.  Internally,  this 
calls  the  Xlib  call  XNextEvent  which  sends  the  batch  of  queued  window  creation  and  win 
dow  map  requests  to  the  server.  Most  window  managers  intercept  the  mapping  request  for 
the  top-level  window  and  draw  a  rubber-band  outline  of  the  application  on  the  screen,  ready 
for  the  user  to  place  or  resize  the  application.  (Each  window  manager  has  a  different  user 
interface  for  positioning  and  sizing  the  application  when  the  rubber-band  outline  appears.)  If 
the  user  simply  places  the  application,  no  new  geometry  negotiation  takes  place.  But  if  the 
user  resizes  the  application,  a  new  round  of  geometry  negotiation  takes  place,  identical  to  the 
process  described  above  where  the  user  specified  a  top-level  widget  geometry. 

In  other  words,  the  process  that  occurs  when  the  user  supplies  a  top-level  geometry  is  the 
same  when  the  user  resizes  the  application  with  the  window  manager  as  it  is  when  the  user 
specifies  top-level  widget  geometry  with  resources  or  the  command  line.  This  process  was 
illustrated  in  Figure  11-2  and  Figure  1 1-3. 

This  process  uses  all  the  methods  except  geometry_manager. 

1 1 .1 .3  Widget  Desires  a  Size  Change 

When  an  application  sets  a  widget  resource  that  affects  what  is  displayed  in  the  widget,  it 
may  be  logical  for  the  widget  to  ask  its  parent  for  a  new  size.  This  would  occur  in  the 
set_values  method  of  the  widget  The  widget  sets  its  desired  geometry  into  its  Core 
geometry  fields  (width,  height,  x,  y,  and  border_width).  Xt  finishes  calling  all  the 
set_values  methods  (because  they  chain),  and  then  calls  xtMakeGeome try- 
Request  to  ask  the  parent  widget  for  a  geometry  change.  Note  that  the  set_yalues  and 
initialize  methods  are  the  only  place  where  widgets  are  allowed  to  set  their  own  size 
directly.  (In  set_values  they  can  do  so  only  because  of  an  xtSetValues  call  to 
change  a  resource  that  affects  geometry.) 

Figure  11-4  shows  what  happens  when  a  widget  requests  a  size  change. 

Of  course,  composite  widgets  often  want  a  size  change  because  their  children  have  asked  to 
be  resized.  The  composite  widget  has  no  knowledge  of  what  caused  the  child's  size  change. 
Therefore,  composite  widgets  call  XtMakeGeometryRequest  themselves  to  see  if  their 
parent  will  allow  them  to  change  size.  Composite  widgets  should  request  such  a  change; 
otherwise  their  parent  may  have  unused  space  or  have  other  children  that  need  more  space. 
However,  handling  the  variety  of  responses  to  the  request  is  not  trivial. 

For  both  simple  and  composite  widgets,  Xt  calls  the  geometry_manager  method  of  the 
parent  widget  when  XtMakeGeometryRequest  is  called,  and  the  method  is  responsible 
for  deciding  whether  to  except,  reject,  or  compromise  on  the  requested  geometry.  The 
geometry_manager  method  may  have  to  ask  its  parent  to  decide  whether  it  can  accept 
its  child's  proposal.  If  so,  it  makes  another  XtMakeGeometryRequest  call.  This  can 
go  on  to  arbitrary  depth,  and  the  final  answer  will  trickle  back  down  to  the  parent  of  the  origi 
nal  requestor.  The  XtMakeGeometryRequest  call  itself  will  change  the  child's 
geometry  if  the  answer  is  yes.  If  the  answer  is  no,  the  child  gets  this  information  and  may  try 
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another  geometry.  If  the  answer  is  a  compromise,  then  the  child  will  get  the  compromise 
information  returned  in  its  call  to  XtMakeGeometryRequest  and  make  another  request 
to  be  able  to  proceed.  More  on  this  interaction  in  Section  1 1.2.5. 

This  process  uses  only  the  geometry_manager  methods  of  each  widget.  However,  this 
method  may  call  xtQueryGeometry  to  determine  the  needs  of  each  of  its  children  before 
replying  to  the  XtMakeGeometryRequest  request  When  the  process  is  finsished,  the 
resize  method  is  called  for  any  widgets  that  have  been  resized.  However,  the 
change_managed  method  is  never  involved. 

11 .1 .4   Application  Resizes  a  Widget 

An  application  may  change  the  size  of  a  widget  by  setting  the  xtNx,  xtNy,  xtNwidth, 
xtNheight,  or  xtNborderWidth  resources  directly  (as  opposed  to  setting  a  resource 
which  indirectly  affects  the  size,  as  covered  in  the  last  section).  If  that  widget  has  no  chil 
dren,  the  widget  code  does  nothing,  but  Xt  queries  the  parent  with  an  XtMakeGeometry 
Request.  The  complete  negotiation  process  as  described  for  xtRealizeWidget  is 
repeated,  except  that  the  current  top-level  Shell  size  is  used  as  a  user-specified  size  (because 
ultimately  it  is). 

Although  the  widget  code  did  nothing,  the  set_values  method  sets  the  new  values  speci 
fied  through  resources  into  the  Core  fields.  If  the  XtMakeGeometryRequest  request  is 
denied  by  the  parent,  Xt  sets  these  Core  fields  back  to  their  original  values.  If  the  parent  sug 
gests  a  compromise,  the  set_values_almost  method,  which  is  described  below,  is 
called. 

If  the  widget  whose  size  is  changed  is  a  widget  with  children,  the  negotiation  process  is  the 
same,  except  that  when  it  is  complete  the  children  of  the  widget  need  to  be  laid  out,  and  if  the 
children  have  children  they  need  to  be  laid  out  too,  and  so  on. 


1 1 .2  Writing  a  Composite  Widget 

The  process  of  writing  a  composite  widget  is  the  same  as  writing  a  simple  widget  You  copy 
the  three  files  of  some  existing  composite  widget,  perhaps  Composite  itself,  make  global 
name  changes  to  make  the  files  a  skeleton  for  a  distinct  class,  and  then  write  new  methods. 

As  mentioned  earlier,  writing  a  general-purpose  composite  widget  is  not  a  trivial  task  and 
should  be  done  only  when  other  options  fail.  Because  composite  widgets  have  no  user  inter 
face,  you  may  be  able  to  find  a  composite  widget  with  the  proper  characteristics  from  another 
widget  set  There  are  several  public  domain  widget  sets  to  look  in.  Note,  however,  that  com 
mercial  widget  set  vendors  may  design  in  a  private  protocol  between  their  composite  widgets 
and  their  children,  which  make  the  composite  widgets  unable  to  correctly  manage  widgets 
from  other  sets.  And  if  you  are  writing  a  commercial  product,  you  may  have  to  pay  a  binary 
license  fee  to  the  commercial  widget  set  vendor  for  each  copy  of  your  product  Especially 
for  large  software  houses,  it  is  a  good  idea  to  have  at  least  one  programmer  adept  at  writing 
composite  widgets  and  the  query_geometry  methods  of  simple  widgets. 
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3]  Application  sets  a  resource  that  changes 
requirements  of  widget  D. 


Xt  calls  resize  method  of  widget  D. 
(If  B  had  suggested  a  compromise,  Xt 

would  call  the  set_values_almost 

method  of  D) 


[2]  Widget  D's  set_values 
method  sets  its  core  width 
and  height  to  its  desired 
size. 


Xt  determines  if  widget  D  has 
proposed  a  new  size.  Xt  calls 

XtMakeGeometryRequest 

to  ask  B  (D's  parent)  about 
D's  proposed  new  size. 


B'S  geometry_manager 

method  accepts,  rejects, 
or  suggests  compromise 
size.  B  is  composite  and 
may  ask  parent  A. 
Assume  B  has  room  and 
accepts  D's  proposal. 


Requests  trickle  up  until  widget  is  found  that: 

•  has  room  to  accomodate  the  change  without 
resizing  itself.  This  widget's 

geometry_manager  accepts  the  Child  proposal. 


or 


never  asks  its  parent  for  a  size  change. 


(Requests  that  reach  the  shell  widget  will  be 
denied  because  most  window  managers  currently 
ignore  shell  size  change  requests) 


Window  Hierarchy 


Figure  11-4.  A  widget  requesting  a  size  change 
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Small  scale  composite  widgets  that  handle  a  small  set  of  circumstances  are  not  difficult  to 
write,  because  you  can  make  a  number  of  simplifying  assumptions.  As  an  example,  this  sec 
tion  describes  a  very  simple  composite  widget  called  ScrollBox,  which  is  designed  to  manage 
a  BitmapEdit  widget  (or  any  other  main  widget)  and  two  Athena  Scroll  widgets.  It  handles 
only  these  three  widgets,  and  they  must  be  added  in  a  particular  order.  Because  we  know  the 
geometry  preferences  of  these  three  widgets  (the  bigger  the  better,  but  no  size  in  particular), 
we  can  dispense  with  querying  them  about  their  preferred  geometry.  We  also  know  that  none 
of  our  children  will  request  to  be  resized.  Therefore,  we  do  not  need  a 
geometry_manager  method. 

A  ScrollBox  widget  is  shown  managing  BitmapEdit  and  two  scrollbars  in  Figure  11-5.* 

The  Athena  Viewport  widget  does  scrollbar  management  in  a  more  general  way  than  does 
ScrollBox.  It  is  a  subclass  of  Form  that  takes  any  main  window  as  a  child  and  creates 
scrollbars.  It  shows  only  a  small  portion  of  the  main  window,  and  uses  the  scrollbars  to 
determine  which  portion  of  the  main  window  is  shown.  But  Viewport  doesn't  work  well  with 
BitmapEdit  because  BitmapEdit  has  a  built-in  ability  to  display  in  a  smaller  window  that 
conflicts  with  Viewport's  efforts.  Besides,  Viewport  is  several  times  larger  and  more  compli 
cated  than  ScrollBox,  because  it  includes  the  scrollbar  callback  functions  and  because  it  hon 
ors  a  child's  geometry  preferences.  ScrollBox  is  a  modest  widget  that  manages  the  geometry 
of  scrollbars,  leaving  their  connection  with  the  main  window  up  to  the  application.  This 
demonstrates  the  essential  elements  of  a  composite  widget  without  too  much  complication.! 

The  ScrollBox  widget  code,  along  with  a  version  of  xbitmap  that  uses  it,  is  available  in  the 
example  source  in  the  ch09  directory.  It  lays  out  its  children  by  adjusting  the  width  and 
height  of  the  three  children  so  that  they  fill  the  ScrollBox  widget,  while  keeping  the  width  of 
the  Scroll  widgets  constant.  The  width  of  the  Scroll  widgets  is  set  through  their  resources, 
and  never  modified  by  ScrollBox. 

The  first  few  sections  below  describe  the  methods  that  are  used  in  ScrollBox  and  that  are 
required  in  all  composite  widgets.  First,  we  discuss  the  Core  initialize,  realize, 
set_values,  resize,  and  query_geometry  methods  as  they  are  used  in  composite 
widgets.  Then,  we  discuss  how  the  ScrollBox  widget  implements  layout  calculations  in  a 
common  routine  called  by  the  set_values,  resize,  and  change_managed  values. 
This  is  followed  by  further  discussion  of  the  change_managed  and  query_geometry 
methods.  Then,  we  go  on  to  discuss  the  methods  not  used  by  ScrollBox,  but  that  would  be 
used  in  more  complicated  composite  widgets,  in  particular  geometry_manager.  Finally, 
we  briefly  discuss  the  methods  available  in  composite  widgets  but  rarely  needed: 
set_values_almost,  insert_child,  and  delete_child. 


*ScrollBox  widens  the  borders  of  its  children,  for  an  unknown  reason.  It  might  as  well  be  admitted  that  there  is  prob 
ably  a  bug  in  it  somewhere! 

fit  is  worth  noting  that  the  Box  widget  fails  miserably  in  managing  scrollbars,  while  Form  is  adequate  but  has  the  an 
noying  characteristic  that  it  resizes  the  width  of  the  scrollbars  as  well  as  their  length,  sometimes  resulting  in  bloated 
or  m in iscule  scrollbars. 
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Figure  1 1-5.  A  ScrollBox  widget  at  two  different  sizes 

11.2.1    Basic  Core  Methods  in  Composite  Widgets 

Both  composite  and  constraint  widgets  are  subclasses  of  Core.  Therefore,  they  have  all  the 
Core  methods  described  in  Chapters  5  and  6.  However,  since  composite  and  constraint  widg 
ets  usually  have  no  input  and  output  semantics,  the  expose  method  is  set  to  NULL  and  the 
widget  has  no  default  translation  table  or  actions.  As  a  result,  all  the  event-oriented  fields  in 
the  Core  class  structure  become  irrelevant  to  composite  and  constraint  widgets. 

But  composite  and  constraint  widgets  do  use  the  Core  initialize,  realize,  and 
set__values  methods.  These  methods  have  the  same  roles  as  for  simple  widgets.  The 
initialize  method  initializes  instance  part  variables  and  checks  initial  resource  values. 
The  realize  method  sets  window  attribute  values  and  then  creates  a  window  for  the 
widget  The  set_values  method  updates  any  instance  part  fields  that  depend  on 
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resources.  Since  composite  and  constraint  widgets  don't  need  GCs,  initialize  and 
set_values  don't  contain  code  to  create  and  change  GCs  as  they  would  in  simple  widg 
ets. 

These  three  methods  for  ScrollBox  are  absolutely  minimal,  and  call  a  common  routine  called 
DoLayout  when  any  actual  sizing  or  positioning  of  widgets  is  required.  The  initial 
ize  method  simply  sets  the  widget's  default  width  and  height,  the  realize  method  is 
inherited,  and  the  set_values  method  changes  the  layout  of  children  when  either  of 
ScrollBox's  two  resources  is  changed.  These  resources  control  the  vertical  and  horizontal 
distance  in  pixels  that  will  be  left  between  the  Scroll  widgets  and  the  main  widget,  and 
between  each  of  these  widgets  and  the  borders  of  ScrollBox.  Example  11-1  shows  the 
set_values  method  of  ScrollBox. 

Example  11-1.  ScrollBox:  the  set_values  method 

/*  ARGSUSED  */ 

static  Boolean  SetValues (current ,  request,  new) 

ScrollBoxWidget  current,  request,  new; 

{ 

/*    need  to   redo   layout    if   h_space   or   v_space   change    */ 
if    ( (new->scrollBox.h_space    !=   current->scrollBox.h_space)     I  I 
(new->scrollBox. v_space    != 

current->scrollBox. v_space) ) 
DoLayout (new) ; 

/*   nothing  to   redisplay,    always   returns   FALSE    */ 
return   FALSE; 
} 

Two  more  Core  methods  are  used  in  composite  widgets:  resize  and  query_geometry. 
The  resize  method  changes  the  layout  of  its  children,  and  is  shown  in  Example  11-2. 

Example  11-2.  ScrollBox:  the  resize  method 

static  void  Resize (w) 
ScrollBoxWidget  w; 
{ 

DoLayout (w) ; 
i 

The  query_geometry  method  answers  the  parent's  inquiry  about  a  size  change  for  this 
composite  widget,  and  is  shown  in  Example  11-3. 

Example  11 -3.  ScrollBox:  the  query_geometry  method 

/*  ARGSUSED  */ 

static  XtGeometryResult  QueryGeometry (widget,  request,  reply_return) 

ScrollBoxWidget  widget; 

XtWidgetGeometry  *request,  *reply_return; 

{ 

XtGeometryResult  result; 

request->request_mode  &=  CWWidth  I  CWHeight; 

if  (request->request_mode  ==  0) 

/*parent  won't  change  w  or  h,  so  nothing  to  re-compute*/ 
return  Xt Geometry Yes; 
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Example  11 -3.  ScrollBox:  the  queiy_geometry  method  (continued) 

/*  if  proposed  size  is  large  enough,  accept  it. 
*  Otherwise,  suggest  our  arbitrary  initial  size.  */ 

if  (request->request_mode  &  CWHeight) 

if  (request->height  <  INITIAL_HEIGHT)  { 

result  =  XtGeometryAlmost; 

reply_return->height  =  INITIAL_HEIGHT; 

reply_return->request_mode  &=  CWHeight; 
} 
else 

result  =  XtGeometryYes; 

if  (request->request_mode  &  CWWidth) 

if  (request->width  <  INITIAL_WIDTH)  { 
result  =  XtGeometryAlmost; 
reply_return->width  =  INITIAL_WIDTH; 
reply_return->request_mode  &=  CWWidth; 
} 

return (result) ; 
} 

Although  the  query_geometry  method  has  the  same  role  in  all  widgets,  composite  and 
simple,  a  composite  widget's  size  preference  depends  on  its  children.  Normally  this  means 
the  query_geometry  method  will  query  its  children  and  try  different  layouts  until  it 
arrives  at  the  geometry,  or  some  approximation  of  it,  suggested  by  its  parent .  This  calcula 
tion  is  complicated  because  the  widget  may  have  any  kind  of  child  and  their  responses  to 
geometry  suggestions  are  unpredictable.  ScrollBox  ignores  this  complexity  because  it  knows 
exactly  what  kinds  of  children  it  will  have  and  what  their  characteristics  are.  Therefore,  its 
query_geometry  method  is  basically  the  same  as  the  query_geometry  method  of  a 
simple  widget. 

To  be  more  precise,  what  this  query_geometry  method  does  is  accept  any  size  suggested 
by  the  parent  which  is  larger  than  the  minimum  useful  size  of  the  application.  When  the  sug 
gested  size  is  too  small,  the  query_geometry  method  uses  the  minimum  useful  size  as  a 
compromise.  Note,  however,  that  this  is  really  hardcoding  the  characteristics  of  the  child  into 
our  composite  widget.  It  would  be  better  to  add  resources  to  control  the  minimum  useful 
size. 


11.2.2    Laying  Out  Child  Widgets 

Composite  widgets  need  to  calculate  a  layout  and  manipulate  their  child  widgets  from 
set_values,  from  resize,  and  from  change_managed.  Therefore,  in  most  compos 
ite  widgets  this  common  code  is  placed  in  a  single  routine  called  DoLayout.  Example  11-4 
shows  the  DoLayout  routine  from  ScrollBox. 
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Example  11-4.  ScrollBox:  private  routine  to  lay  out  child  widgets 

/*  ARGSUSED  */ 
static  DoLayout (sbw) 
ScrollBoxWidget  sbw; 

Widget  main,  vscroll,  hscroll; 

Widget  child; 

Dimension  mw,  mh;     /*  main  window  */ 

Dimension  vh;         /*  vertical  scrollbar  length  (height)  */ 

Dimension  hw;         /*  horizontal  scrollbar  length  (width)  */ 

Position  vx; 

Position  hy; 

int  i; 

if  (sbw->composite .num_children  !=  3) 

fprintf (stderr,  "scrollBox:  must  manage  exactly  \ 
three  widgets . \n") ; 


for  (i  =  0;  i  <  sbw->composite .num_children; 
child  =  sbw->composite .children [i] ; 
if  ( IXtlsManaged (child) ) 

fprintf (stderr,  "scrollBox:  all  three  widgets  \ 

must  be  managed. \n")  ; 
} 

/* 

*  Child  one  is  the  main  window,  two  is  the  vertical 

*  scrollbar,  and  three  is  the  horizontal  scrollbar. 
*/ 

main  =  sbw->composite .children [0] ; 
vscroll  =  sbw->composite .children [ 1] ; 
hscroll  =  sbw->composite .children [2] ; 

/* 

*  Size  all  three  widgets  so  that  space  is  fully  utilized. 
*/ 

mw  =  sbw->core .width  -  (2  *  sbw->scrollBox.h_space)  - 

vscroll->core .width  -  (2  *  vscroll->core .border_width)  - 
(2  *  main->core .border_width) ; 

mh  =  sbw— >core . height  —  (2  *  sbw->scrollBox. v_space)  - 

hscroll->core .height  -  (2  *  hscroll->core .border_width)  - 
(2  *  main->core .border_width) ; 

vx  =  main->core.x  +  mw  +  sbw->scrollBox.h_space  + 

main->core .border_width  +  vscroll->core .border_width; 

hy  =  main->core.y  +  mh  +  sbw->scrollBox. v_space  + 

main->core .border_width  +  hscroll->core .border_width; 

vh  =  mh;   /*  scrollbars  are  always  same  length  as  main  window  */ 
hw  =  mw; 

XtResizeWidget (main,  mw,  mh) ; 

XtResizeWidget (vscroll,  vscroll->core .width,  vh)  ; 
XtMoveWidget (vscroll,  vx,  vscroll->core .y) ; 

XtResizeWidget (hscroll,  hw,  hscroll->core .height) ; 
XtMoveWidget (hscroll,  hscroll->core .x,  hy)  ; 
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In  general,  DoLayout  moves  and  resizes  the  child  widgets  according  to  its  layout  policy. 
This  routine  may  query  the  children  with  XtQueryGeometry  before  making  decisions, 
but  it  is  not  required  to.  In  this  case,  there  is  no  need  to  because  ScrollBox  handles  only  two 
types  of  widgets  with  no  size  preferences. 

DoLayout  is  passed  only  one  argument,  ScrollBox's  own  widget  ID  (a  pointer  to  its  widget 
instance  structure).  But  the  composite  children  field  in  ScrollBox's  instance  structure  is 
an  array  of  the  IDs  of  all  the  children,  and  num_children  is  the  number  of  children.* 

When  each  child  is  added  to  a  composite  widget,  its  ID  is  added  to  the  children  field  of 
the  composite  part  of  the  instance  structure,  and  the  num_children  field  is  incremented. 
Therefore,  the  code  to  lay  out  the  children  is  usually  a  loop  that  treats  each  child  one  at  a 
time.  This  often  takes  two  passes,  since  the  routine  needs  to  know  which  children  are 
managed  before  it  can  determine  their  final  geometries.  All  children,  even  unmanaged  ones, 
are  listed  in  the  children  and  num_children  fields. 

This  particular  DoLayout  procedure  makes  sure  that  there  are  exactly  three  children  and 
that  they  are  all  managed.  Then,  it  calculates  the  positions  and  sizes  for  all  the  children  so 
that  they  will  fill  all  the  available  space  in  ScrollBox's  own  window.  Finally,  it  calls  xt- 
ResizeWidget  and  xtMoveWidget,  which  check  to  see  if  there  was  any  change  before 
making  Xlib  calls  to  move  and  resize  the  windows. 

11.2.3   The  changejnanaged  Method 

In  every  composite  widget,  the  change_managed  method  is  called  once  (and  only  once, 
even  when  there  are  multiple  children)  during  the  xtRealizeWidget  process  to  deter 
mine  an  application's  initial  layout.  change_managed  is  also  called  when  an  application 
later  unmanages  a  managed  widget  or  manages  an  unmanaged  widget  (as  long  as  the  xt- 
NmappedWhenManaged  resource  has  its  default  value).  Therefore,  change_managed 
also  calls  DoLayout. 

An  application  unmanages  a  widget  to  remove  the  widget  from  visibility  without  destroying 
it,  and  at  the  same  time  to  tell  the  composite  widget  to  change  the  layout  of  the  remaining 
widgets  to  fill  the  gap.  This  is  done  by  calling  XtUnmanageChild  or  xtUnmanage- 
Children.  The  application  can  then  make  the  composite  widget  redisplay  the  widget  by 
calling  XtManageChild  or  xtManageChildren.  This  response  depends  on  the  Core 
xtNmappedwhenManaged  resource  having  its  default  value,  TRUE.  When  set  to  FALSE, 
the  management  state  has  no  effect  on  mapping,  and  the  application  must  call  xtMap- 
Widget  and  xtUnmapWidget  instead.  Usually  an  application  does  this  so  that  a  widget 
will  become  invisible  without  triggering  a  re-layout  to  fill  in  the  space  it  has  vacated.  There 
fore,  change_managed  need  not  check  the  XtNmapWhenManaged  resource  of  each 
child. 


"Incidentally,  the  children  and  num_children  fields  are  resources.  However,  they  are  for  reading  only  from 
outside  of  the  widget  code;  the  application  should  never  set  them  with  XtSetValues. 
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You  have  now  seen  all  of  the  code  of  ScrollBox!  To  summarize,  a  very  basic  composite 
widget  such  as  ScrollBox  has  a  standard  initialize  method,  resize  and 
change_managed  methods  that  just  call  DoLayout,  and  a  set_values  method  that 
calls  DoLayout  when  any  resource  that  affects  layout  is  changed.  The  DoLayout  rou 
tine  actually  lays  out  the  children.  The  widget's  query_geometry  method  is  basically 
just  like  a  simple  widget's  query_geometry.  Now  we'll  move  on  to  describe  what  may 
be  added  to  this  skeleton  to  make  more  fully-featured  composite  widgets. 

11.2.4  XtQueryGeometry  and  the  query_geometry  Method 

We  have  mentioned  that  XtQueryGeometry  just  calls  a  child's  query_geometry 
method,  but  not  the  details  of  how  this  works.  The  query_geometry  method  for  simple 
widgets  is  described  in  Chapter  6,  Basic  Widget  Methods.  The  role  of  this  method  in  compo 
site  widgets  is  the  same,  but  the  details  of  its  job  are  different.  You  may  recall  that  this 
method  is  passed  pointers  to  two  xtwidget Geometry  structures,  one  which  specifies  the 
parent's  proposed  geometry,  and  the  other  which  is  used  by  the  child  to  return  a  compromise 
geometry.  These  two  structures  are  allocated  by  the  method  that  calls  XtQuery 
Geometry,  and  passed  as  pointers  to  that  call.  The  XtGeometryResult  enum 
returned  by  the  query_geometry  method  is  passed  right  through  as  the  returned  value  of 
XtQueryGeometry. 

Composite  and  constraint  widgets  play  the  role  of  both  parent  and  child.  When  you  write  a 
composite  widget,  you  may  call  XtQueryGeometry  in  several  places  to  get  the  child's 
response  to  your  proposed  size.  You  will  also  need  to  write  a  query_geometry  method 
so  that  your  widget  can  responds  to  its  parent's  XtQueryGeometry  request. 

A  query_geometry  method  in  a  composite  widget  should  base  its  response  on  the  size 
preferences  of  its  children.  It  should  calculate  a  new  layout  based  on  the  proposed  geometry 
passed  in,  and  then  query  its  children  to  get  their  opinions  of  their  new  geometry.  If  any  of 
the  children  is  a  composite  widget,  they  may  query  their  children,  and  so  on.  Therefore, 
these  requests  tend  to  trickle  down  to  the  lowest  widget  in  the  hierarchy.  ScrollBox  took  the 
biggest  shortcuts  in  its  query_geometry  method.  Not  only  didn't  it  query  its  children, 
but  it  hardcoded  its  response  based  on  the  characteristics  of  the  kind  of  main  window  it 
expected.  This  would  be  the  first  place  to  begin  improving  ScrollBox. 

Note,  however,  that  a  composite  widget  is  allowed  to  be  authoritarian  and  not  ask  its  children 
whether  they  like  the  sizes  they  are  about  to  be  given.  However,  this  kind  of  composite 
widget  will  not  be  suitable  as  a  parent  of  a  widget  that  really  needs  certain  size  preferences. 

11.2.5  XtMakeGeometryRequest  and  the  geometry_manager  Method 

XtMakeGeometryRequest  calls  are  made  for  two  reasons.  First,  when  a  composite 
widget  honors  its  children's  size  preferences,  it  may  find  that  its  current  size  is  inadequate  to 
lay  out  its  children.  In  this  case,  it  should  ask  its  parent  to  be  resized  by  calling  XtMake 
GeometryRequest.  Second,  Xt  calls  XtMakeGeometryRequest  for  a  widget  when 
the  application  has  changed  a  resource  that  affects  geometry. 
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As  mentioned  above,  xtMakeGeometryRequest  calls  the  parent's 
geometry_manager  method.  The  parent's  geometry_manager  has  the  job  of  decid 
ing  whether  the  size  proposed  by  the  child  is  acceptable.  A  subclass  of  Composite  must 
either  define  a  geometry_manager  method,  or  set  this  field  in  the  class  structure  to 
NULL,  because  there  is  no  default  method  to  inherit.  The  xtlnheritGeometry- 
Manager  symbol  can  be  used  only  in  subclasses  of  a  class  that  defines  a 
geometry_manager  method. 

Any  composite  widget  that  wants  to  allow  its  children  to  suggest  resizing  will  require  a 
geometry_manager  method  of  its  own. 

The  way  the  arguments  and  returned  values  are  passed  between  XtMakeGeometry 
Request  and  the  parent's  geometry_manager  method  is  almost  exactly  parallel  to  the 
way  XtQueryGeometry  calls  the  child's  query_geometry  method.  Both  calls  take 
pointers  to  two  structures  of  the  same  types  where  one  is  used  for  a  returned  compromise. 
Both  take  no  more  arguments  other  than  the  widget  ID.  Both  return  an  enum  value  of  type 
XtGeometryResult.  The  returned  value  of  the  geometry_manager  method  is,  gen 
erally  speaking,  passed  through  as  the  returned  value  of  XtMakeGeometryRequest. 
Review  Section  6.6  so  that  these  structures,  their  fields  and  values,  and  the  returned  values 
are  fresh  in  your  mind. 

One  difference  between  the  way  the  query_geometry  and  geometry_manager 
methods  are  invoked  is  that  the  geometry_manager  method  can  return  a  fourth  enum 
value,  XtGeometryDone  (in  addition  to  Xt  Geometry  Yes,  XtGeometryNo,  and  Xt- 
GeometryAlmost).  Table  11-1  summarizes  the  return  codes  of  the 
geometry_manager  method. 

Table  11-1.  Return  Codes  of  geometry_manager  Method 


Code 


XtGeometryNo 
XtGeometryAlmost 
Xt Geometry Yes 


XtGeometryDone 


Description 


Requested  change  is  denied 

A  compromise  is  suggested 

Requested  change  is  accepted,  let  xtMakeGeometryRe 

quest  make  change 

Requested  change  is  accepted,  I  have  made  change 


XtGeometryDone  means  that  geometry_manager  approves  of  the  change  and  has 
actually  made  the  change.  XtMakeGeometryRequest  never  returns  XtGeometry 
Done  though;  it  returns  XtGeometryYes  when  the  geometry_manager  returns  Xt- 
GeometryYes  or  XtGeometryDone.  When  the  geometry_manager  returns  Xt 
GeometryYes,  the  XtMakeGeometryRequest  call  itself  makes  the  size  change.  All 
these  shenanigans  simply  allow  the  parent  to  make  the  size  change  by  calling  its  normal  lay 
out  code  or  to  let  XtMakeGeometryRequest  do  it,  depending  on  which  is  most  conve 
nient 

The  second  difference  is  that  XtMakeGeometryRequest  and  the 
geometry_manager  method  interpret  the  XtGeometryNo  returned  value  differently. 
For  XtMakeGeometryRequest  and  geometry_manager,  it  has  its  intuitive 
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meaning  that  the  requested  change  is  denied.  For  query_geometry  and  xt Query- 
Geometry,  the  symbol  should  really  be  XtGeometryNoChange.  Since  this  symbol 
doesn't  exist,  xtGeometryNo  has  to  do  double  duty,  meaning  in  this  case  that  the  pro 
posed  size  and  current  size  are  the  same. 

The  final  difference  is  an  additional  mask  for  the  request_mode  field  of  the  Xt- 
widget Geometry  structure  that  contains  the  proposed  change.  In  XtMakeGeometry- 
Request  requests,  the  mask  xtCWQueryOnly  can  be  ORed  with  the  masks  that  identify 
which  fields  in  the  proposed  geometry  the  child  considers  important.  This  indicates  that  the 
proposed  change  should  not  be  made,  but  that  the  geometry_manager  method  should  fill 
in  the  return  structure  with  the  changes  it  would  have  made.  This  flag  is  used  whenever  a 
widget  is  making  an  XtMakeGeometryRequest  from  its  geometry_manager 
method:  these  requests  are  intermediate  (triggered  by  requests  from  children).  The  compos 
ite  widget  does  not  actually  want  to  be  resized  until  it  has  made  a  suggestion  for  its  own  size 
to  its  parent,  received  an  answer  from  the  parent,  recalculated  the  layout  of  its  children,  and 
queried  its  children,  if  necessary,  to  see  that  the  new  size  is  adequate  for  everybody. 

This  also  makes  it  obvious  that  the  geometry_manager  method  you  write  for  your  com 
posite  widget  must  be  prepared  to  handle  the  XtCWQueryOnly  mask.  It  should  calculate  a 
layout  but  not  actually  move  or  resize  any  widgets. 

ScrollBox  does  not  need  a  geomet  ry_manager  method  because  it  knows  that  its  children 
will  never  make  geometry  requests.  However,  any  composite  widget  that  accepts  all  kinds  of 
children  requires  a  geometry__manager  method.  In  Section  11.4.6  below,  the 
geometry_manager  method  of  the  Form  widget  is  shown  and  described. 

Similar  to  XtMakeGeometryRequest,  but  less  general,  is  XtMakeResizeRequest. 
Instead  of  passing  two  structures,  XtMakeResizeRequest  passes  two  width  and  height 
pairs.  Otherwise,  the  results  of  this  call  are  the  same. 


11.2.6   The  set_values_al most  Method 

As  mentioned  above,  a  child  widget  may  request  a  geometry  change  for  one  of  three  reasons: 

•  The  application  just  called  Xt  Set  Values  and  set  a  geometry  field.  In  this  case,  Xt 
makes  the  geometry  request  to  the  parent  to  allow  the  parent  to  overrule  or  modify  the 
change. 

•  The  application  just  called  xt  Set  Values  and  set  a  resource  that  affects  geometry,  like 
the  string  displayed  in  a  Label  widget  The  set_values  method  of  the  child  changes 
the  geometry  fields  in  the  widget  directly.  Then  Xt  makes  a  geometry  request  to  the  par 
ent,  to  allow  the  parent  to  overrule  or  modify  the  change. 

•  The  child  may  decide  it  needs  more  or  less  room  because  of  some  kind  of  user  input,  or 
because  its  own  children  need  more  or  less  room.   In  this  case,  it  calls  XtMake 
GeometryRequest  itself,  and  handles  the  various  returned  values  itself.  If  the  widget 
wants  to  use  set_values_almost  to  make  compromise  suggestions  (since  it  is 
designed  for  that  purpose  and  may  be  there  anyway),  the  widget  will  have  to  call  the 
method  itself. 
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In  the  first  two  cases,  Xt  calls  xtMakeGeometryRequest,  while  in  the  third  case,  the 
child  must  call  the  function  itself.  If  the  returned  value  is  Xt  Geometry  Yes,  the  Xt 
MakeGeometryRequest  call  itself  (or  Xt)  has  resized  the  child. 

When  XtMakeGeometryRequest  is  called  by  Xt,  and  its  returned  value  is  xt- 
GeometryAlmost  or  XtGeometryNo,  Xt  calls  the  set_values_almost  method 
of  the  widget  whose  geometry  is  changing.*  The  job  of  set_values_almost  is  to  pro 
pose  a  different  geometry  to  the  parent  Once  set_values_almost  proposes  a  new 
geometry,  Xt  calls  the  parent's  geometry_manager  method  again,  and  the  cycle  repeats 
until  the  geometry_manager  returns  XtGeometryYes  or  XtGeometryDone.  Fig 
ure  11-6  illustrates  this  process. 

Most  widgets  inherit  this  method  from  the  Core  widget  by  specifying  xtlnheritSet- 
Va  lues  Almost  in  the  Core  class  part  initialization.  This  inherited  method  always 
approves  the  suggestion  made  by  the  parent  geometry_manager  method.  If  your  widget 
really  depends  on  being  certain  sizes,  however,  you  will  need  to  write  a  set_val- 
ues_almost  method.  You  should  never  specify  a  NULL  set_values_almost 
method.  If  you  do,  Xt  will  print  a  warning  message  when  set_values_almost  would 
have  been  called,  and  continue  as  if  it  had  been  called  and  returned  XtGeometryYes 
approving  the  change. 

The  set_values_almost  method  is  passed  pointers  to  two  Xtwidget Geometry 
structures:  request  and  reply.  The  request  structure  contains  the  child's  original 
request  and  reply  includes  the  geometry_manager  method's  compromise  geometry  if 
geometry_manager  returned  XtGeometryAlmost.  To  accept  the  compromise,  the 
procedure  must  copy  the  contents  of  the  reply  geometry  into  the  request  geometry;  to  attempt 
an  alternate  geometry,  the  procedure  may  modify  any  part  of  the  request  argument;  to  termi 
nate  the  geometry  negotiation  and  retain  the  original  geometry,  the  procedure  must  set 
request->request_mode  to  zero. 

If  geometry_manager  returned  XtGeometryNo,  it  will  not  have  generated  a  compro 
mise.  In  this  case,  the  set_values_almost  method  may  suggest  a  new  geometry,  but  it 
is  probably  not  worth  it  since  the  method  has  no  information  upon  which  to  base  its  changes 
to  its  previous  suggestion.  The  set_values_almost  method  at  this  point  should  usually 
just  set  request ->request_mode  to  zero  to  terminate  the  geometry  negotiation. 

1.2.7   The  insert_child  and  delete_child  Methods 

The  Composite  class  has  an  instance  part  structure  that  contains  an  array  of  all  the  widget's 
children  (even  those  not  currently  managed),  the  current  number  of  children,  and  the  total 
number  of  child  slots  available.  The  insert_child  method  inserts  the  ID  of  a  child  into 
this  array.  It  is  called  when  the  child  is  created  by  a  call  to  xtCreatewidget  or  xt- 
CreateManagedWidget.  Most  widgets  inherit  the  insert_child  method  from  the 
Composite  class  by  specifying  the  symbolic  constant  xt Inherit insertChild  in  the 


*Several  facts  described  here  differ  from  the  R3  Xt  specification  document  (the  initial  X  consortium  standard).  No 
known  implementation  of  Xt  ever  followed  those  specifications.  This  section  describes  the  R3  and  R4  implementa 
tion,  which  works  as  described  in  the  R4  specification. 
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J]  Xt  calls  parent 

geometry_manager 

again. 


;2_    Parent's  geometry_manager 

analyses  child  suggestion  and 
returns  value  and  possibly  a 
compromise.  Must  make  sure 
this  is  not  an  infinite  loop. 
XtGeometryYes  means 

compromise  accepted. 


If  returned  value  is 

XtGeometryNo  Or 
XtGeomet ryAlmost , 

Xt  calls  child's 

set_values_almost 

method. 


Child's  set_values_almost 

method  proposes  a  new 
geometry  based  on  information 
passed  in,  or  gives  up.  If  new 
geometry  back  to  [j] . 


Figure  1 1-6.  Geometry  negotiation  by  the  set_values_almost  method 

class  structure  initialization.  A  class  would  replace  the  default  insert_child  method  to 
control  the  position  of  each  child  added,  or  to  limit  the  number  or  classes  of  widgets  that  can 
be  added. 

A  composite  widget  can  control  the  position  of  each  child  added  by  calling  a  function  whose 
pointer  is  stored  in  the  instance  part  field  insert _pos  it  ion.  The  function  should  return 
the  number  of  widgets  before  the  widget  The  xtNinsertPosition  resource  sets  this 
function  pointer.  The  default  insert_position  function  returns  the  current  number  of 
children.  Of  course,  because  this  resource's  value  is  a  function  pointer,  it  can  be  specified  in 
the  application  only  at  run  time,  never  through  the  resource  files  or  command  line. 

The  delete_child  method  removes  the  ID  of  a  child  from  the  child  array  and  is  called 
when  the  application  calls  xtDestroyWidget.  This  method  is  almost  always  inherited 
from  Composite  by  specifying  the  symbolic  constant  xtlnheritDeleteChild  in  the 
class  structure  initialization. 
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11 .3  How  Constraint  Management  Works 

The  first  thing  to  realize  about  constraint  widgets  is  that  everything  said  about  composite 
widgets  is  still  true.  Because  Constraint  is  a  subclass  of  Composite,  all  the  methods 
described  above  are  still  present  and  have  the  same  tasks.  However,  constraint  widgets  also 
maintain  a  structure  full  of  data  attached  to  each  child,  set  through  resources.  Every  time  it 
lays  out  the  children,  the  constraint  widget  reads  this  data  to  determine  how  to  handle  that 
child.  Of  course,  it  still  may  query  each  children  to  get  its  opinion  of  a  new  size.  The  con 
straint  information  adds  another  level  of  complexity  to  the  situation. 

Like  composite  widgets,  constraint  widgets  can  be  drastically  simplified  by  reducing  flexibil 
ity  and  features.  The  Athena  Form  widget,  for  example,  never  queries  its  children  for  their 
geometry  input,  and  never  asks  its  parent  for  a  size  change.  Furthermore,  its  constraints  for 
each  child  are  quite  limited.  This  makes  Form  quite  short  and  simple,  but  also  means  that  it 
doesn't  always  do  the  right  thing. 


1 1 .4  Writing  a  Constraint  Widget 

The  following  sections  describe  the  portions  of  the  Athena  Form  widget  that  relate  to 
geometry  management.  This  will  give  you  a  birds-eye  view  of  constraints  in  action. 

11.4.1    The  Core  Resource  List 

The  Form  widget  has  only  one  resource  of  its  own,  xtNdef  aultDistance,  as  shown  in 
Example  11-5.  This  resource  is  used  only  as  the  default  for  two  of  the  Constraint  resources, 
XtNhorizDistance  and  XtNvertDistance.  XtNdef  aultDistance  is  used  to 
set  the  instance  field  def  ault_spacing,  which  is  used  in  only  one  place  in  the  widget,  in 
the  Constraint  initialize  method  described  in  Section  11.4.4. 

Example  1 1-5.  Form:  the  Core  resource  list 

#define  Offset (field)  XtOf f set (FormWidget,  form. field) 
static  XtResource  resources []  =  { 

XtNdef aultDistance, 

XtCThickness, 

XtRInt, 

sizeof (int) , 

Offset (default_spacing) , 

XtRImmediate, 

(caddr_t) 4 

} 

}; 
tundef   Offset 
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11.4.2   The  Constraint  Resource  List 

The  Form  widget  has  three  groups  of  constraint  resources.  xtNhorizDistance,  xt- 
Nf romHoriz,  XtNvertDistance,  and  XtNfromVert  together  control  the  initial 
position  of  a  child.  XtNtop,  XtNlef  t,  XtNbottom,  and  XtNright  govern  reposition 
ing  of  the  child  when  Form  is  resized.  The  xtNresizable  resource  controls  whether  the 
geometry_manager  of  this  widget  will  honor  requests  to  change  the  geometry  of  this 
child.  Note  that  XtNresizable  does  not  control  whether  this  constraint  widget  can  resize 
a  child — only  whether  or  not  it  will  do  so  because  of  a  request  from  the  child.* 

For  more  details  about  how  these  constraint  resources  work,  read  about  them  on  the  reference 
page  for  the  Form  widget  in  Volume  Five,  X  Toolkit  Intrinsics  Reference  Manual. 

Constraint  resources  are  also  called  simply  constraints,  particularly  because  they  are  stored 
in  a  Core  instance  field  called  constraints.  Example  11-6  shows  Form's  constraint 
resource  list. 

Example  11 -6.  Form:  constraint  resource  list 
static   XtEdgeType    defEdge   =   XtRubber; 

#define   Of f set (field)    XtOf f set (FormConstraints,    form. field) 
static   XtResource    f ormConstraintResources [ ]    =    { 

II       < 

XtNhorizDistance, 

11       XtCThickness, 

XtRInt, 

sizeof (int ) , 

Offset (dx) , 
I|       XtRImmediate, 

(caddr_t) DEFAULTVALUE 

II       ) , 

II       {XtNf romHoriz,  XtCWidget,  XtRWidget,  sizeof (Widget) , 

Offset (horizjbase) ,  XtRWidget,  (caddr_t) NULL} , 
{XtNvertDistance,  XtCThickness,  XtRInt,  sizeof (int), 

Offset (dy),  XtRImmediate,  (caddr_t) DEFAULTVALUE }, 
{XtNfromVert,  XtCWidget,  XtRWidget,  sizeof (Widget ), 
Offset (vertjbase) ,  XtRWidget,  (caddr_t ) NULL} , 

{XtNtop,  XtCEdge,  XtREdgeType,  sizeof (XtEdgeType) , 

Off set (top),  XtREdgeType,  (caddr_t) SdefEdge } , 
{XtNbottom,  XtCEdge,  XtREdgeType,  sizeof (XtEdgeType) , 

Of f set (bottom) ,  XtREdgeType,  (caddr_t) SdefEdge } , 
{XtNleft,  XtCEdge,  XtREdgeType,  sizeof (XtEdgeType) , 

Offset (left) ,  XtREdgeType,  (caddr_t ) SdefEdge } , 
{XtNright,  XtCEdge,  XtREdgeType,  sizeof (XtEdgeType) , 

Offset (right) ,  XtREdgeType,  (caddr_t ) sdefEdge } , 

{XtNresizable,  XtCBoolean,  XtRBoolean,  sizeof (Boolean) , 

Of fset (allow_resize) ,  XtRImmediate,  (caddr_t)0}, 
}; 
tundef  Offset 


*The  fact  that  Form  does  not  provide  individual  control  over  the  resizability  of  each  child  is  a  major  weakness. 
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The  corresponding  data  structure  that  this  resource  list  references,  FormConstraints,  is 
defined  in  the  private  include  file  for  the  widget  Its  definition  is  shown  in  Example  1 1-7. 

Example  11 -7.  Form:  constraint  data  structure 

typedef  struct  _FormConstraintsPart  { 

II  /* 

*  Constraint  Resources. 

III  */ 

XtEdgeType  top,  bottom,  /*  where  to  drag  edge  on  resize  */ 

left,  right; 

int  dx;  /*  desired  horiz  offset  */ 

int  dy;  /*  desired  vertical  offset  */ 

Widget  horiz_base;  /*  measure  dx  from  here  if  non-null  */ 

Widget  vert_base;  /*  measure  dy  from  here  if  non-null  */ 

Boolean  allow_resize;  /*  TRUE  if  child  may  request  resize  */ 

/* 

*  Private  constraint  variables. 

*  These  store  the  dimensions  of  the  child  prior  to  layout. 
Ill   */ 

int         virtual_width,  virtual_height; 

III  /* 

*  Size  of  this  child  as  it  would  be  if  we  did  not  impose  the 

*  constraint  that  its  width  and  height  must  be  greater  than  zero  (0) 
*/ 

LayoutState  layout_state;    /*  temporary  layout  state    */ 
}  FormConstraintsPart; 

typedef  struct  _FormConstraintsRec  { 

FormConstraintsPart  form; 
}  FormConstraintsRec,  *FormConstraints; 

The  constraints  part  structure  should  be  considered  an  instance  part  structure.  This  structure 
has  public  fields  set  through  resources  and  private  fields  that  hold  state  data,  just  like  an 
instance  part  structure.  Note  also  that  the  FormConstraints  structure  is  built  the  same 
way  as  instance  structures,  by  combining  part  structures  for  each  class  into  a  complete  con 
straint  structure.  This  allows  subclasses  of  Form  to  create  their  own  constraint  part  structure 
and  add  it  after  the  Form  constraint  part. 

When  a  widget  is  created  as  a  child  of  a  constraint  widget,  the  constraint  instance  structure 
(FormConstraintsRec,  in  this  case)  is  placed  in  the  constraints  field  of  the  Core 
instance  structure.  Xt  makes  the  constraint  resources  stored  there  sellable,  like  resources 
defined  by  the  child  even  though  they  are  actually  defined  and  used  by  the  parent. 

11.4.3   Class  Structure  Initialization 

The  Form  class  is  a  subclass  of  Constraint.  Therefore,  its  class  structure  contains  class  parts 
for  Core,  Composite,  Constraint,  and  Form.  Example  11-8  shows  the  class  structure  initiali 
zation  of  Form.  Several  methods  referenced  here  have  not  been  discussed  so  far  in  this  book. 
They  are  the  Core  methods  class_initialize  and  class_jpart_init,  and  the 
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Constraint  methods  initialize  and  set_values.  These  and  all  the  geometry  man 
agement-related  methods  of  Form  will  be  discussed  in  Section  11.4.6. 

Example  11 -8.  Form:  class  structure  initialization 
FormClassRec    formClassRec   =    { 


{  /*  Core  class  fields 
/*  superclass 
/*  class_name 
/*  widget_size 
/*  class_initialize 
/*  class_part_init 
/*  class_inited 
/*  initialize 
/*  initialize_hook 
/*  realize 
/*  actions 
/*  num_actions 
/*  resources 
/*  num_resources 
/*  xrm_class 
/*  compress  motion 


*/ 
*/ 
*/ 
*/ 

*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 


/*  compress_exposure  */ 
/*  compress_enterleave*/ 
/*  visible  interest 


destroy 

resize 

expose 


/*  set_values 

/*  set_values_hook 

/*  set  values  almost 


*/ 

*/ 
*/ 
*/ 

*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
*/ 
/*  display_accelerator*/ 


get_values_hook 
accept_focus 
version 

callback_private 
tm  table 


/*  query_geometry 


/*  extension 


/ 


(Widget  Class)  sconstraintClassRec, 

"Form", 

sizeof  (FormRec)  , 

Class  Initialize, 

ClassP  art  Initialize, 

FALSE, 

Initialize, 

NULL, 

Xt  Inner  itRealize, 

NULL, 

0, 

resources, 

XtNumber  (resources)  , 

NULLQUARK, 

TRUE, 

TRUE, 

TRUE, 

FALSE, 

NULL, 

Resize, 

Xt  Inner  itExpose, 

SetValues, 

NULL, 

Xt  Inner  it  SetValuesAlmost, 

NULL, 

NULL, 

XtVersion, 

NULL, 

NULL, 

Pref  erredGeometry, 

XtlnheritDisplayAccelerator, 

NULL 


{  /*  Composite  class  fields 


/*  geometry_manager 

/*  change_managed 

/*  insert_child 

/*  delete_child 

/*  extension 


*/ 

*/ 
'*/ 
*/ 
*/ 


GeometryManager, 

ChangeManaged, 

XtlnheritlnsertChild, 

XtlnheritDeleteChild, 

NULL 


{  /*  Constraint  class  fields  */ 


/*  subresourses 

/*  subresource_count 

/*  constraint_size 

/*  initialize 


destroy 

set_values 

extension 


*/  formConstraintResources, 

*/  XtNumber (formConstraintResources) , 

*/  sizeof (FormConstraintsRec) , 

*/  Constraintlnitialize, 

*/  NULL, 

*/  ConstraintSetValues, 

*/  NULL 


{  /*  Form  class  fields   */ 
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Example  11 -8.  Form:  class  structure  initialization  (continued) 
/*    layout  */        Layout 

WidgetClass    formWidgetClass   =    (WidgetClass) sformClassRec; 

Note  that  the  Form  class  is  the  first  widget  we  have  shown  that  defines  a  class  part  field — a 
method  of  its  own,  called  layout.  Since  this  method  is  not  known  to  Xt,  Xt  will  never  call 
it  The  widget  must  invoke  this  method  itself  at  the  appropriate  times  (you  will  see  this  invo 
cation  in  the  methods  below).  This  code  is  made  into  a  method  instead  of  just  a  private  func 
tion  only  to  make  it  possible  for  subclasses  of  this  widget  to  inherit  or  replace  the  method. 
Having  such  a  method  requires  that  the  widget  have  a  class_part_init  method  to 
handle  the  inheritance  if  a  subclass  specifies  the  layout  method  with  the  symbolic  constant 
Xt  Inherit  Layout  (also  defined  in  this  class's  private  header  file). 

Section  11.2.1  described  which  Core  and  Composite  methods  are  required  for  composite 
widgets,  and  how  to  initialize  the  other  Core  and  Composite  fields  for  a  composite  widget. 
The  same  is  true  for  constraint  widgets. 

However,  the  Constraint  part  is  probably  new  to  you.  The  ConstraintClassPart 
structure  contains  seven  fields.  The  first  three  fields  are  where  the  constraint  resource  list,  the 
number  of  resources,  and  the  size  of  the  constraint  instance  structure  are  entered.  This 
resource  list  and  instance  structure  were  described  in  the  last  section.  These  fields  are  analo 
gous  to  the  resources,  num_resources,  and  widget_size  fields  in  the  Core  class 
part. 

The  three  next  fields,  initialize,  destroy,  and  set_values  are  methods  defined 
by  the  Constraint  class.  These  methods  have  the  same  field  names  as  methods  of  Core,  but 
are  fields  of  a  different  structure,  and  contain  pointers  to  different  functions  that  you  may 
need  to  write.  To  differentiate  Constraint  methods  from  the  Core  methods,  we  will  precede 
the  names  of  Constraint  fields  with  the  word  "Constraint"  and  the  names  of  Core  fields  with 
the  word  "Core"  throughout  this  chapter. 

Two  of  the  three  Constraint  methods  will  be  described  where  they  fit  in  below.  We'll 
describe  one  of  them,  Constraint  destroy,  now,  because  it  is  not  used  in  Form  and  is  less 
likely  to  be  needed  in  the  constraint  widgets  you  may  write.  The  Constraint  destroy 
method  is  called  when  a  child  is  destroyed,  just  before  the  Core  destroy  method  of  the 
child.  It  is  responsible  for  freeing  any  memory  allocated  by  the  constraint  widget  that  was 
used  to  manage  that  child.  However,  like  the  Core  destroy  method,  it  does  not  need  to 
free  memory  allocated  by  Xt,  such  as  the  constraint  data  structure  for  the  child. 


The  Constraint  initialize  Method 

The  Constraint  initialize  method  is  called  when  a  widget  is  created,  soon  after  the  Core 
initialize  method.  It  has  the  same  two  responsibilities  as  the  Core  initialize  method, 
and  one  additional  responsibility.  It  must: 

•     Validate  the  ranges  of  resource  settings,  since  they  may  be  user-supplied. 
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•  Compute  the  value  of  any  private  constraint  instance  part  fields  that  depend  on  constraint 
resource  values  (public  constraint  instance  part  fields). 

•  Set  child  Core  geometry  fields  to  match  the  constraint  resources.  For  example,  if  a  con 
straint  for  the  maximum  height  of  a  widget  is  set  and  the  initial  value  set  by  the  child  is 
larger,  the  Constraint  initialize  method  resets  the  height  field  in  the  Core  instance 
structure. 

However,  like  the  Core  initialize  method,  the  Constraint  initialize  method  is 
responsible  only  for  constraint  resources  and  for  Core  geometry  resources.  It  need  not  handle 
any  resources  of  superclasses  (other  than  the  Core  geometry  resources). 

The  Form  widget  performs  only  one  of  the  tasks  listed  above,  initializing  constraint 
resources.  In  Form's  case,  the  Constraint  initialize  method  (shown  in  Example  11-9) 
simply  sets  the  initial  values  of  the  XtNvertDistance  and  XtNhorizDistance  con 
straint  resources  to  the  current  value  of  the  xtNdef  aultDistance  Form  resource,  unless 
the  user  has  specified  a  value  for  either  constraint  resource.  This  is  done  only  so  that  the 
application  can  set  the  Form  resource  once  and  have  it  apply  to  every  child  that  does  not 
override  the  value. 

Form  doesn't  validate  the  values  of  any  user-supplied  resource  values,  as  it  should.  For 
example,  the  user  may  supply  a  negative  value  for  the  XtNhorizDistance  or  Xt 
NvertDistance  resources.  This  would  certainly  make  the  layout  look  bad,  but  it  could 
also  cause  the  Form  widget  to  go  into  an  infinite  loop  on  geometry  negotiations.  In  general, 
all  initialize  methods  in  Core  and  Constraint  should  check  for  ranges  of  reasonable 
values  of  resources  where  this  makes  sense  (doing  this  in  set_values  is  also  a  good  idea 
to  give  the  programmer  good  warning  messages).  This  eliminates  a  source  of  potential  bugs. 

Example  11 -9.  Form:  the  Constraint  initialize  method 

/*  ARGSUSED  */ 

static  void  Constraintlnitialize (request,  new) 

Widget  request,  new; 
{ 

FormConstraints  form  =  (FormConstraints) new->core .constraints; 

FormWidget  fw  =  (FormWidget) new->core .parent; 

if  (form->form.dx  —  DEFAULTVALUE) 

form->form.dx  =  fw->form.default_spacing; 

if    (form->form.dy   ==   I>EFAULTVALUE ) 

form->form.dy  =  fw->form.default_spacing; 

} 

Note  that  the  Constraint  instance  part  structure  (FormConstraints)  and  the  Form  widget 
instance  structure  (FormWidget)  are  accessed  by  casting  two  different  fields  of  the  child's 
instance  structure  passed  in. 

The  Constraint  initialize  method  and  the  child's  Core  initialize  are  passed  the 
same  two  copies  of  the  child's  instance  structure:  request,  and  new.  The  request 
widget  is  the  widget  as  originally  requested.  The  new  widget  starts  with  the  values  in  the 
request,  but  it  has  already  been  updated  by  calling  all  superclass  initialize  methods. 
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The  class_part_init  Method 

The  class_part_init  method  should  be  present  in  a  class  that  defines  new  methods  in 
its  class  part  structure.  These  new  methods  will  never  be  called  by  Xt  since  Xt  has  no  knowl 
edge  of  when  to  call  them.  They  can  only  be  invoked  directly  from  the  widget  code.  The 
purpose  of  making  them  methods  instead  of  just  functions  is  to  allow  subclasses  to  inherit  or 
replace  the  functions.  The  class_jpart_init  method  actually  resolves  this  inheritance 
by  setting  each  method  field  to  the  pointer  provided  by  this  class  (the  subclass  is  inheriting 
the  method)  or  to  the  pointer  provided  by  the  subclass  (the  subclass  is  replacing  the  method). 
Example  11-10  shows  a  class_part_init  method  for  a  class  that  defines  only  one  new 
method  in  its  class  part  structure.  This  method  is  the  Form  widget's  layout  code. 

Example  11-10.  The  class_part_init  method  of  Form. 

static   void   ClassPartlnitialize (class) 

WidgetClass    class; 
{ 

register   FormWidgetClass   c   =    (FormWidgetClass)    class; 

if    (c->form_class. layout   ==   XtlnheritLayout) 

c->form_class. layout   =   Layout; 
} 

The  XtlnheritLayout  symbol  is  defined  in  the  private  include  file  for  any  class  that 
defines  new  class  part  methods  (one  for  each  new  method).  Its  value  is  always  _xt- 
Inherit. 

Form  itself  sets  the  layout  field  to  a  pointer  to  its  Layout  function.  When  its 
class_part_init  method  is  called  when  the  first  instance  of  Form  is  created,  it  does 
nothing  because  the  layout  field  is  not  XtlnheritLayout.  When  a  subclass  is  defined 
that  sets  the  layout  field  to  a  function,  the  same  thing  happens:  Form's 
class_part_init  method  is  called  because  it  is  chained  downward  (the 
class_part_init  methods  of  all  superclasses  are  called),  and  it  still  does  nothing 
because  the  layout  field  is  not  XtlnheritLayout.  Thus,  the  subclass  has  replaced 
Form's  method.  But  if  the  subclass  sets  the  layout  field  to  XtlnheritLayout,  Form's 
class_part_init  method  sets  the  field  to  its  own  Layout  function.  The  subclass  has 
inherited  Form's  method. 

Usually,  only  the  class  that  defines  a  particular  new  method  resolves  the  inheritance  by 
checking  for  the  value  of  that  field  in  its  class_part_init  method.  However,  if  a  sub 
class  also  checks  for  the  value — if  for  example  a  subclass  of  Form  checked  for  Xtlnherit 
Layout — the  downward  chaining  means  that  the  subclass  class_part_init  method 
would  take  precedence. 
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11.4.6  The  geometry_manager  Method 

geometry_manager  methods  handle  requests  from  the  children  to  be  resized.  Therefore, 
they  typically  use  the  proposed  geometry  passed  in  from  the  child  to  calculate  a  new  experi 
mental  layout,  and  actually  move  and  resize  the  children  if  the  new  layout  is  acceptable. 
However,  when  the  request  is  just  a  query,  the  method  should  be  able  to  return  the  same 
values  without  actually  moving  or  resizing  anything. 

The  Form  geometry_manager  method  is  shown  in  Example  11-11.  Form  uses  the 
allow_resize  field  (the  XtNresizable  resource)  to  determine  whether  to  even  con 
sider  the  resize  request  Then,  if  the  request  specifies  a  width  and  height,  Form  will  accept 
the  change  by  returning  xtGeometryYes.  The  XtMakeGeometryRequest  call  that 
invoked  the  geometry_manager  will  actually  make  the  geometry  change  before  return 
ing  to  the  child's  code.  If  the  request  specifies  any  other  geometry  change  (border  width, 
position,  or  stacking  order),  Form  will  deny  the  request  Finally,  if  the  request  was  not  a 
query,  Form  actually  does  the  new  layout.  Note  that  Form  returns  xtGeomet  ryDone  if  it 
has  made  the  geometry  changes,  and  returns  XtGeometryYes  when  it  agrees  with  the 
changes  but  has  not  made  them  (due  to  a  query). 

Note  that  the  allowed  structure  in  this  routine  could  be  replaced  by  individual  width  and 
height  variables.  Also  note  that  the  reply  structure  is  never  filled.  This  is  used  only 
when  the  geometry_manager  method  wants  to  suggest  a  compromise. 

II     Example  11-11.  Form:  the  geometry_manager  method 

/*  ARGSUSED  */ 

static  XtGeometryResult  GeometryManager (w,  request,  reply) 

Widget  w; 

XtWidgetGeometry  *request; 

XtWidgetGeometry  *reply;     /*  RETURN  */ 
{ 

FormConstraints  form  =  (FormConstraints) w->core. constraints; 

XtWidgetGeometry  allowed; 

if  ( (request->request_mode  &  ~ (XtCWQueryOnly  | 
CWWidth  |  CWHeight))  || 
! form->form. allow_resize) 
return  XtGeometryNo; 

if  (request->request_mode  &  CWWidth) 

allowed. width  =  request->width; 
else 

allowed. width  =  w->core .width; 

if  (request->request_mode  &  CWHeight) 

allowed. height  =  request->height; 
else 

allowed. height  =  w->core .height; 

if  (allowed. width  ==  w->core .width  &&  allowed. height  == 

w->core . height ) 
return  XtGeometryNo; 

if  ( ! (request->request_mode  &  XtCWQueryOnly))  { 
/*  reset  virtual  width  and  height.  */ 
form->form. virtual  width  =  w->core .width  =  allowed .width; 
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Example  11  -11.  Form:  the  geometry_manager  method  (continued) 

form->form.  virtual_height  =  w->core  .height  =  allowed.  height; 
Ref  igureLocations  (  (FormWidget  )  w->core  .parent  ); 
} 

return  XtGeometryYes; 
} 

The  Ref  igureLocations  called  from  the  geometry_manager  method  is  a  private 
function  analogous  to  the  DoLayout  routine  used  in  ScrollBox,  except  that  Ref  igure 
Locations  calls  Form's  layout  method  that  contains  the  actual  layout  code  so  that  the 
method  can  be  inherited  or  replaced  by  subclasses.  The  layout  method  calculates  a  layout 
and  moves  and  resizes  the  children.  Ref  igureLocations  is  also  called  from  the 
change_managed  method,  as  described  in  Section  11.4.9.  Example  11-12  shows  the 
Ref  igureLocations  function  and  Form's  layout  method,  which  it  calls.  (The  if 
statement  that  branches  depending  on  the  value  of  the  no_re  figure  field  allows  an  appli 
cation  to  turn  relayout  on  and  off,  as  described  in  Section  1  1.4.1  1.) 

Example  11-12.  Form:  private  functions:  RefigureLocations  and  the  layout  method 

static  void  Ref  igureLocations  (w) 

FormWidget  w; 
{ 

/*  no_refigure  supports  the  relayout  recalculation 

delay  described  later  in  this  chapter   */ 
if  (w->f  orm.  no_ref  igure)  { 

w->form.needs_relayout  =  TRUE; 
} 
else  { 

(*  (  (FormWidgetClass)  w->core  .  widget_class)  ->f  orm_class  .  layout) 

(  w,  w->core  .width,  w->core  .height  ); 
w->form.  needs_relayout  =  FALSE; 


/*  ARGSUSED  */ 

static  Boolean  Layout  (fw,  width,  height) 

FormWidget  fw; 

Dimension  width,  height; 
{ 

int  num_children  =  fw->composite  .num_children; 

WidgetList  children  =  fw->composite  .children; 

Widget  *childP; 

Position  maxx,  maxy; 

static  void  LayoutChild  (  )  ; 

Boolean  ret_val; 

for  (childP  =  children;  childP  -  children  <  num_children; 
childP  +  -f)  { 

FormConstraints  form  =  (FormConstraints) 

(*childP)  ->core.  constraints; 

form->form.layout_state  =  LayoutPending; 
} 

maxx  =  maxy  =  1; 
/* 

*  Layout  children  one  at  a  time,  and  determine 

*  necessary  size  for  self 
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Example  11-12.    Form:  private  functions:  RefigureLocations  and  the  layout  method  (con 
tinued) 

*/ 

for  (childP  =  children;  child?  -  children 

<  num_children;  childP++)  { 
/* 

*  Layout  child  then  find  position  of  bottom  right 

*  outside  corner  of  child 
*/ 

if  (XtIsManaged(*childP)  )  { 
Position  x,  y; 
LayoutChild  (*childP)  ; 
x  =  (*childP)->core.x  +  (*childP)  ->core  .width 

+  (  (*childP)->core.border_width  «  1); 
y  =  (*childP)->core.y  +  (*childP)  ->core  .height 

+  (  (*childP)  ->core.border_width  «  1); 
if  (maxx  <  x)  maxx  =  x; 
if  (maxy  <  y)  maxy  =  y; 


fw->form.preferred_width  =  (maxx  +=  fw->f  orm.  default_spacing)  ; 
fw->form.pref  erred_height  =  (maxy  +=  fw->form.  default_spacing)  ; 

/   Now  ask  parent  to  resize  us.   If  it  says  Almost,  accept  the 
compromise.   If  Almost  and  parent  chose  smaller  size,  or  No 
and  we  were  smaller  than  necessary,  children  will  be  clipped, 
not  laid  out  again. 
/ 
if  (fw->form.resize_in_layout 

&&  (maxx  !=  fw->core  .width  II  maxy  !=  fw->core  .height)  )  { 
XtGeometryResult  result; 
result  =  XtMakeResizeRequest  (  fw,  (Dimension)  maxx, 

(Dimension)  maxy,  (Dimension*)  Smaxx,  (Dimension*)  Smaxy  ) 
if  (result  ==  XtGeometryAlmost) 

result  =  XtMakeResizeRequest  (  fw,  (Dimension)  maxx, 

(Dimension)  maxy,  NULL,  NULL  ); 
fw->form.old_width   =  fw->core  .width; 
fw->form.old_height  =  fw->core  .height  ; 
ret_val  =  (result  ==  XtGeometryYes)  ; 
}  else  ret_val  =  FALSE; 

return  ret_val; 
} 

The  layout  method  treats  one  child  at  a  time,  as  usual.  It  first  initializes  the 
layout_state  private  constraint  instance  field  of  each  child  to  LayoutPending;  the 
LayoutChild  routine  will  start  from  this  value.  Next,  it  calls  LayoutChild  for  each 
child,  and  at  the  same  time  keeps  a  running  total  of  the  sizes  of  the  children  so  that  when  the 
loop  is  finished  it  knows  how  big  to  be  to  fit  all  the  children.  Finally,  it  requests  of  its  parent 
that  it  be  just  big  enough  to  fit  its  children.  If  the  parent  denies  the  request,  the  code  makes 
no  attempt  to  make  another  request.  If  the  parent  offers  a  compromise,  it  is  accepted.  In 
either  case,  the  Form  widget  may  be  too  big  or  too  small  to  fit  its  children.  If  it  is  too  small, 
some  of  its  children  will  be  clipped. 
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The  LayoutChild  routine  is  shown  in  Example  1 1-13.  What  it  does  is  simple,  although  it 
is  a  little  hard  to  follow  because  it  is  called  recursively.  It  moves  the  child  according  to  the 
XtNf  romHoriz  and  XtNf  romVert  constraint  resources.*  These  resources  specify  that 
a  child  be  placed  to  the  right  of  or  below  another,  particular  child. 

Example  11-13.  Form:  the  LayoutChild  private  function 

static  void  LayoutChild (w) 
Widget  w; 

FormConstraints  form  =  (FormConstraints) w->core .constraints; 
Position  x,  y; 
Widget  ref; 

switch  (f orm->form. layout_state)  { 

case  LayoutPending: 

form->form.layout_state  =  LayoutlnProgress; 
break; 

case  LayoutDone : 
return; 

case  LayoutlnProgress: 

String  subs [2] ; 

Cardinal  num_subs  =  2; 

subs[0]  =  w->core .name; 

subs[l]  =  w->core .parent->core .name; 

XtAppWarningMsg(XtWidgetToApplicationContext (w) , 

"constraintLoop", "xawFormLayout", "XawToolkitError", 
"constraint  loop  detected  while  laying  out  child  '%sf  in  \ 

FormWidget  '%s'", 

subs,  &num_subs) ; 

return; 

x  =  form->f orm.dx; 
y  =  f orm->form.dy; 
if  ((ref  =  form->form.horiz_base)  !=  (Widget) NULL)  { 

LayoutChild (ref) ; 

x  +=  ref->core.x  +  ref->core .width  +  (ref->core .border_width 
«  1); 

if  ((ref  =  form->form.vert_base)  !=  (Widget)NULL)  { 
LayoutChild (ref ) ; 

y  +=  ref->core.y  +  ref->core .height  +  (ref->core.border_width 
«  1); 

XtMoveWidget (  w,  x,  y  )  ; 

form->form. layout_state  =  LayoutDone; 

If  neither  XtNf  romHoriz  nor  XtNf  romVert  are  set  for  the  child,  it  is  simply  placed  the 
default  distance  from  the  top-left  corner  of  the  Form.  When  one  child  is  set,  the  next  child 

*Form  resizes  children  only  when  it  is  resized — never  during  normal  layout 
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must  be  placed  relative  to  that  child.  However,  the  other  child  may  be  later  in  the  list  and  not 
properly  positioned  yet.  Therefore,  the  code  calls  LayoutChild  to  lay  out  the  child  that 
this  child  is  positioned  relative  to. 

The  layout_state  field  catches  circular  settings  for  the  XtNf  romHoriz  and  Xt- 
Nf  romvert  resources.  For  example,  if  widget  A  is  specified  to  the  right  of  widget  B,  and 
widget  B  is  specified  to  the  right  of  widget  A,  there  is  no  solution.  LayoutChild  would  be 
caught  in  an  infinite  loop  of  calling  itself.  When  first  called  from  the  layout  method,  the 
layout_state  is  LayoutPending.  This  is  changed  to  Layout  InProgress  in  the 
switch  statement.  If  the  function  is  called  again  for  the  same  child,  this  state  will  cause  the 
warning  message  to  be  printed  and  the  function  to  exit  The  Form  widget  does  not  exit — it 
just  gives  up  processing  the  invalid  constraint  resource  setting  and  prints  a  warning  message. 


11.4.7   The  resize  Method 

The  resize  method  calculates  a  layout  to  fit  in  the  new  dimensions  of  Form  and  moves  and 
resizes  the  children  accordingly.  Form's  resize  method  is  shown  in  Example  11-14.  It 
consists  of  a  loop  that  treats  each  managed  child  one  at  a  time.  The  position  and  dimensions 
of  each  child  are  calculated  with  the  help  of  the  private  function  Transf  ormCoord  (also 
shown  in  Example  11-14)  and  the  child  is  moved  and  resized.  Transf  ormCoord  handles 
one  parameter  at  a  time,  and  uses  a  position,  the  size  before  resizing,  the  size  after  resizing, 
and  the  constraints  settings  to  arrive  at  the  appropriate  value  for  the  parameter.  The  old 
width  and  height  of  the  Form  widget  are  initialized  in  the  Core  initialize  method  and 
updated  at  the  end  of  the  resize  method. 

II     Example  11 -14.  Form:  the  resize  method 

static   void   Resize (w) 

Widget    w; 
{ 

FormWidget  fw  =  (FormWidget ) w; 

WidgetList  children  =  fw->composite . children; 

int  num_children  =  f w->composite .num_children; 

Widget  *childP; 

Position  x,  y; 

Dimension  width,  height; 

for  (childP  =  children;  child?  -  children  <  num_children; 

childP++)  { 
FormConstraints  form  =  (FormConstraints) 

(*childP) ->core .constraints; 
if  ( !XtIsManaged(*childP) )  continue; 
x  =  Transf ormCoord (  ( *childP) ->core .x,  fw->form.old_width, 

fw->core .width,  form->form. left  ); 

y  -••  Transf  ormCoord  (  (  *childP) ->core  .y,  fw->form.old_height, 
fw->core. height,  form->f orm. top  ); 

form->form.virtual_width  = 

Transf ormCoord ( (Position) ( (*childP) ->core.x 

+  form->form. virtual_width 

+  2  *  (*childP) ->core.border_width)  , 

f w->f orm . old_width,  f w->core . width, 

form->f orm. right  ) 
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Example  11 -14.  Form:  the  resize  method  (continued) 

-    (x   +   2    *     (*childP)->core.border_width) ; 

form->form. virtual_height  = 

TransformCoord ( (Position) ( (*childP) ->core .y 

+  form->form. virtual_height 

+  2  *  (*childP)->core.border_width) , 

f w->f orm . old_height ,  f w->core . height , 

form->form. bottom  ) 

(  y  +  2  *  (*childP)->core.border_width) ; 

width  =  (Dimension) 

(form->form. virtual_width  <  1)  ?  1  : 

form->form.virtual_width; 
height  =  (Dimension) 

(form->form.virtual_height  <!)?!: 
f orm->f orm . virtual_height ; 

XtMoveWidget (  (*childP),  x,  y  ); 
XtResizeWidget (  (*childP),  width,  height, 

(*childP) ->core .border_width  ); 
} 

fw->form. old_width  =  fw->core .width; 
fw->form.old_height  =  fw->core .height ; 

} 

static  Position  TransformCoord (loc,  old,  new,  type) 
register  Position  loc; 
Dimension  old,  new; 
XtEdgeType  type; 
{ 

if  (type  ==  XtRubber)  { 
if  (  ( (int)  old)  >  0) 

loc  =  (loc  *  new)  /  old; 
} 

else  if  (type  ==  XtChainBottom  I  I  type  ==  XtChainRight) 
loc  +=  (Position) new  -  (Position) old; 

/* 

*  I  don't  see  any  problem  with  returning  values 

*  less  than  zero. 
*/ 

return  (loc) ; 
} 

This  resize  method  stores  the  new  size  of  the  children  in  the  virtual_width  and 
virtual_height  constraint  part  fields,  and  uses  their  previous  values  to  arrive  at  the 
new  size.  This  is  done  because  Form's  XtNtop,  XtNbottom,  xtNlef  t,  and  xtNright 
constraints  specify  the  geometry  of  the  child  based  on  its  previous  geometry. 

Notice  that  the  for  loop  in  this  particular  resize  method  loops  through  the  children 
directly,  using  pointer  arithmetic.  This  is  equivalent  to  using  a  loop  that  increments  an  inte 
ger  and  then  uses  the  integer  to  index  the  children  array.  For  example,  the  first  five  lines 
of  the  loop  could  also  be  expressed  as: 
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int  i; 

for  (i  =  0;  i  <  num_children; 

FormConstraints  form  =  (FormConstraints) 
(children [i] ) ->core. constraints; 
if  ( IXtlsManaged (*childP) )  continue; 
x  =  Transf ormCoord (  (children [i] ) ->core .  x, 

fw->form.old  width,  fw->core .width,  form->form. left  ); 


11.4.8   The  Core  and  Constraint  set_values  Methods 

When  the  application  calls  xt  Set  Values  to  set  the  resources  of  a  child  of  a  constraint 
widget,  Xt  calls  the  child's  Core  set_values  method  and  then  the  parent's  Constraint 
set_values  method.  Both  methods  are  passed  the  same  arguments.  Constraint 
set_values  validates  the  ranges  of  constraint  resource  settings  and  computes  the  value  of 
any  private  constraint  instance  part  fields  that  depend  on  constraint  resource  values.  It 
should  also  set  child  Core  geometry  fields  to  match  the  changes  in  constraint  resources.  For 
example,  if  a  constraint  for  the  maximum  height  of  a  widget  is  changed  to  a  value  smaller 
than  the  widget's  current  height,  then  the  Constraint  set_values  procedure  should  reset 
the  height  field  in  the  widget 

Both  Core  and  Constraint  set_values  must  return  TRUE  or  FALSE  to  indicate  whether 
redisplay  of  the  widget  is  necessary.  For  composite  and  constraint  widgets,  this  value  is 
usually  meaningless  because  there  is  nothing  to  redisplay.  But  these  might  be  useful  if,  for 
some  reason,  you  write  a  composite  widget  that  does  have  display  semantics. 

Form  defines  both  the  Core  and  Constraint  set_values  methods  as  empty  functions  that 
return  FALSE.  An  easier  way  to  do  this  is  to  specify  NULL  for  them  in  the  class  structure  ini 
tialization. 


11.4.9   The  change_managed  Method 

The  change_managed  method  is  responsible  for  making  the  initial  layout  of  an  applica 
tion  and  changing  the  layout  when  any  child  changes  management  state.  Form's 
change_managed  method  (shown  in  Example  11-15)  calls  Ref  igureLocations  to 
actually  do  a  layout  (RefigureLocations  is  a  private  routine  equivalent  to  Do- 
Layout  in  ScrollBox,  which  was  described  in  Section  11.4.6.)  Form's 
change_managed  method  also  stores  the  previous  size  of  the  children  in  the 
virtual_width  and  virtual_height  constraint  part  fields,  for  use  in  the  resize 
method  as  described  in  Section  11.4.7. 

Example  11 -15.  Form:  the  change_managed  method 

static   void  ChangeManaged (w) 

Widget    w; 
{ 

FormWidget  fw  =  (FormWidget ) w; 

FormConstraints  form; 

WidgetList  children,  childP; 
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Example  11-15.  Form:  the  change_managed  method  (continued) 

int  num_children  =  fw->composite .num_children; 
Widget  child; 

/* 

*  Reset  virtual  width  and  height  for  all  children. 
*/ 

for  (children  =  childP  =  fw->composite. children; 

childP  -  children  <  num_children;  childP++)  { 
child  =  *childP; 
if  (XtlsManaged (child) )  { 

form  =  (FormConstraints) child->core. constraints; 

if  (  child->core. width  !=  1) 

form->form. virtual_width  =  (int)  child->core .width; 
if  (  child->core. height  !=  1) 

form->form. virtual_height  =  (int)  child->core .height ; 

Ref igureLocations (  (FormWidget ) w  ); 

} 


11.4.10   The  query_geometry  Method 

Form's  query_geometry  method  (shown  in  Example  11-16)  is  the  minimal  version 
almost  identical  to  the  one  described  for  simple  widgets  in  Chapter  6,  Basic  Widget  Methods. 
The  preferred_width  and  preferred_height  instance  variables  are  set  in  the 
Form  class  Layout  method  to  the  size  that  just  fits  the  current  layout. 

Example  11 -16.  Form:  the  query_geometry  method 

static   XtGeometryResult   Pref erredGeometry (    widget,    request,    reply      ) 

Widget   widget; 

XtWidgetGeometry    *request,     *reply; 
{ 

FormWidget    w   =    (FormWidget) widget ; 

reply->width   =   w->form.pref erred_width; 
reply->height    =   w->form.preferred_height; 
reply->request_mode   =   CWWidth    I    CWHeight; 
if    (       request->request_mode    &     (CWWidth    I    CWHeight)    == 
reply->request_mode    &    CWWidth    |    CWHeight 
&&    request->width   ==    reply->width 
&&    request->height   -=    reply->height) 
return   XtGeometryYes; 
else    if    (reply->width   ==   w->core .width   &&    reply->height   == 

w->core .height) 
return   XtGeometryNo; 
else 

return   XtGeometryAlmost  ; 
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1 1 .4.1 1    Delaying  Geometry  Recalculation 

During  an  application's  initial  layout,  the  change_managed  method  of  a  composite 
widget  is  called  only  once  even  though  many  children  may  have  been  managed.  However, 
after  that,  change_managed  is  called  once  for  every  child  that  changes  management 
state.  Many  composite  or  constraint  widgets,  especially  ones  that  have  complicated  layout 
code,  provide  a  public  function  (such  as  the  one  shown  in  Example  11-17)  that  the  applica 
tion  can  call  to  turn  off  layout  recalculation  until  a  group  of  windows  is  managed  or 
unmanaged,  and  then  call  again  to  trigger  recalculation  once  the  whole  group  of  children  has 
been  managed  or  unmanaged. 

To  implement  this  delay,  you  need  an  instance  variable  to  hold  a  Boolean  value  indicating 
whether  to  delay  or  not  (no_ref  igure,  in  this  case).  You  set  and  unset  this  variable  in 
this  public  routine  and  you  test  it  in  change_managed.* 

Example  11-17.  Form:  the  public  function  for  delay  ing  calls  to  change_managed 

void  XawFormDoLayout (w,  doit) 

Widget  w; 

Boolean  doit;  /*  FALSE,  don't  recalculate;  TRUE,  do  */ 

{ 

register  FormWidget  fw  =  (FormWidget) w; 

fw->form.no_ref igure  =  Idoit; 

if  (  XtlsRealized (w)  &&  fw->form.needs_re layout  ) 
Ref igureLocations (  fw  ); 


11.5  Compound  Widgets 

A  compound  widget  is  a  combination  of  widgets  that  are  put  together  to  make  a  higher-level, 
user-interface  object.  For  example,  Xaw  makes  the  Dialog  widget  by  combining  the  Label 
and  Text  or  Command  widgets  in  a  widget  that  is  actually  a  trivial  subclass  of  the  Form 
widget  Dialog  creates  the  Label,  Text,  and  Form  widgets  in  its  initialize  method,  and 
sets  constraint  resources  to  position  them.  Dialog  provides  its  own  resource  list  to  allow  an 
application  to  configure  some  characteristics  of  its  children.  The  application  can  manipulate 
the  children  only  through  these  resources,  because  it  cannot  access  the  widget  IDs  of  the 
subwidgets  of  Dialog  without  breaking  the  rules  of  data  hiding.  Thus,  compound  widgets 
provide  programming  convenience,  but  they  make  it  more  difficult  to  take  advantage  of  all 
the  configurable  aspects  of  the  subwidgets. 

The  main  widget  of  the  compound  widget  may  be  a  subclass  of  Core,  Composite,  or  Con 
straint  If  it  is  a  subclass  of  Core,  the  widget  manages  the  positions  and  sizes  of  its  children 
manually  whenever  it  is  resized.  The  success  of  this  strategy  is  dependent  on  the  children 
never  trying  to  resize  themselves,  and  on  the  application  never  trying  to  resize  the  children 


*XawFormDoLayout  is  called  XtFormDoLayout  in  Release  3. 
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directly.*  The  latter  will  not  be  a  problem  unless  the  application  breaks  the  data-hiding  rules 
by  manipulating  the  child  directly.  The  Text  widget  is  an  example  of  this  kind  of  widget  It 
creates  and  manages  its  own  scrollbar. 

Compound  widgets  normally  define  only  a  few  methods  and  inherit  the  rest.  Compound 
widgets  based  on  Core  will  move  and  resize  their  children  manually  in  their  resize 
method.  If  the  widget  is  a  subclass  of  Composite  or  Constraint,  the  normal  geometry  man 
agement  facilities  manage  the  position  and  size  of  the  children.  If  it  is  a  subclass  of  Con 
straint,  the  main  widget  sets  the  constraints  of  the  children  to  control  the  geometry  manage 
ment  process  by  providing  a  Constraint  initialize  method. 

A  compound  widget  always  needs  a  destroy  method  that  destroys  the  children  it  created. 
Compound  widgets  also  need  a  set_yalues  method  to  manage  their  resources. 


11.6  Stacking  Order 

We  promised  earlier  to  say  a  bit  more  about  how  composite  or  constraint  widgets  can  control 
the  stacking  order  of  their  children.  We  noted  that  this  must  be  done  manually,  because  Xt 
doesn't  provide  much  support  for  it 

There  is  no  Core  resource  for  stacking  order,  and  therefore  it  can't  be  set  with  xtSet- 
Values  unless  you  define  the  resources  in  your  own  widget  class.  Xt  provides  no  call  to 
restack  windows;  you  must  use  the  Xlib  functions  XConf  igurewindow,  XRestack- 
Windows,  XRaiseWindow,  or  XLowerWindow.  When  a  widget  suggests  a  stacking 
order  for  itself  through  its  query_geometry  method,  Xt  takes  care  of  making  the 
required  Xlib  call  if  the  parent  agrees  with  the  change.  However,  stacking  requests  of  unreal 
ized  widgets  have  no  effect  (so  stacking  order  won't  be  set  this  way  in  the  initial  geometry 
negotiation).  Therefore,  the  most  robust  method  to  handle  stacking  order  is  for  your  compos 
ite  widget  to  make  the  appropriate  Xlib  calls  directly  to  change  the  stacking  order  of  its  chil 
dren.  XRestackwindows  is  probably  the  best  call  to  use.  Since  restacking  the  windows 
doesn't  change  their  requirements  for  screen  space,  it  shouldn't  effect  either  the  parent  or  the 
children  adversely.  The  appropriate  place  to  call  XRestackwindows  depends  on  when 
you  want  to  change  the  stacking  order.  (Note  that  the  stacking  change  won't  become  visible 
until  the  next  time  Xt  is  waiting  for  an  event.) 


*When  a  child  of  a  simple  widget  calls  XtMakeGeometryRequest  because  it  wants  to  change  its  size,  Xt- 
MakeGeometryRequest  always  makes  the  requested  changes  and  returns  XtGeometryYes.  Therefore,  a 
simple  widget  parent  really  has  no  control  over  its  child  if  the  child  wants  to  resize  itself.  A  simple  widget  cannot 
even  tell  that  the  child  has  resized  itself. 
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Menus,  Gadgets, 
and  Cascaded  Pop  Ups 


This  chapter  describes  how  menus  work,  and  several  ways  to  create  menu 
widgets.  One  of  these  ways  involves  the  use  of  windowless  widgets,  or  gad 
gets.  This  chapter  also  describes  how  to  use  more  advanced  features  of  the 
Xt  pop-up  mechanism,  including  modal  cascades,  to  implement  cascading 
pop-up  menus. 

In  This  Chapter: 

Menu  Styles  and  Implementation 347 

How  Menus  are  Popped  Up 348 

Menu  Panes  349 

Several  Ways  to  Create  and  Use  Menus 351 

A  Spring-Loaded  Menu:  Pointer  Grabbing 351 

A  Drop-Down  Menu  359 
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In  Chapter  2,  we  show  a  simple  example  that  pops  up  a  dialog  box.  This  chapter  is  much 
more  thorough  in  describing  the  Xt  facilities  for  managing  pop  ups,  and  focuses  on  pop-up 
menus. 

Although  the  menus  provided  by  various  widget  sets  vary  greatly  in  the  way  they  look  and  in 
the  way  they  are  used  in  the  application,  the  underlying  Xt  facilities  for  managing  them  are 
the  same.  This  chapter  presents  a  series  of  examples  based  on  R3  and  R4  Athena  widgets 
that  implement  menus  in  different  ways.  While  some  of  the  techniques  shown  may  be  hidden 
within  the  menu  widgets  provided  in  commercial  widget  sets,  it  will  help  you  understand 
menus  better  to  see  the  underlying  techniques  fully  exposed  and  explored. 

This  chapter  also  discusses  cascaded  pop  ups — pop  ups  that  call  other  pop  ups — and  the 
event  management  necessary  to  have  pop  ups  that  shut  out  other  input  elsewhere  in  the  appli 
cation  and  system. 

Finally,  this  chapter  discusses  windowless  widgets  called  gadgets,  which  have  been  designed 
to  reduce  window  system  overhead.  Their  most  important  use  is  to  implement  the  panes  in 
menu  widgets.  Gadgets  were  originally  developed  by  Digital  as  a  part  of  DECWindows,  and 
have  been  carried  over  into  the  version  of  Xt  shipped  with  Motif.  They  are  supported  by  the 
MIT  Intrinsics  beginning  in  Release  4  (R4).  As  an  example  of  a  widget  that  manages  gad 
gets,  we  will  show  the  R4  SimpleMenu  widget  and  its  gadget  children. 

In  this  chapter,  we  are  using  the  term  menu  broadly,  to  refer  to  any  user-interface  element 
that  lists  many  options  and  allows  the  user  to  select  one  or  more.  A  menu  might  consist  of  a 
list  of  commands,  only  one  of  which  can  be  selected  at  a  time,  a  list  of  nonexclusive  Boolean 
settings  that  can  be  turned  on  or  off,  or  a  list  of  exclusive  choices  (such  as  the  colors  or  pat 
terns  for  a  paint  palette).  A  menu  that  invokes  commands  will  start  in  the  same  state  each 
time,  while  the  other  two  types  may  have  different  contents  in  any  particular  invocation, 
showing  the  settings  invoked  the  previous  time  or  all  previous  times,  or  a  modified  list  of 
choices. 

Menus  are  one  of  the  most  important  user-interface  elements  in  window-based  applications. 
They  offer  the  same  feature  as  Command  buttons — a  way  for  the  user  to  invoke  application 
functions  or  set  parameters — but  in  a  more  organized  and  more  easily  accessible  fashion 
when  there  are  more  than  a  few  buttons. 
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Figure  12-1  compares  a  menu  to  a  box  full  of  buttons. 
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Figure  12-1.  Command  widgets  in  a  button  box,  and  the  same  commands  as  a  menu 

The  menu  takes  up  less  space  because  only  its  title  is  visible  until  it  is  called  up.*  As  a  result, 
you  can  have  more  menus  than  you  could  have  permanent  button  boxes.  Commands  can  be 
presented  in  smaller,  more  closely  related  groups.  The  user  will  spend  less  time  searching  for 
the  desired  command. 

The  commands  in  the  menu  are  also  easier  to  read  because  they  are  arranged  one  per  row. 
The  commands  in  the  menu  may  even  be  easier  to  invoke  because  it  is  more  natural  to  drag 
the  mouse  up  and  down  than  from  side  to  side.  And  last  but  not  least,  menus  avoid  the  worst 
problem  with  button  boxes:  when  the  application  is  resized,  button  boxes  may  place  each 
command  widget  in  a  different  position,  making  it  more  difficult  for  the  user  to  find  com 
mands,  t 

Many  of  the  applications  in  the  core  distribution  from  MIT  use  button  boxes  instead  of 
menus  because  there  was  no  menu  widget  in  the  Athena  widget  set  until  Release  4.  Those 
applications  that  do  use  menus  have  implemented  them  directly  with  Xlib.  All  commercial 
widget  sets  supply  one  or  more  menu  widgets. 

If  you  have  only  the  Release  3  Athena  widgets,  you  can  simulate  a  rudimentary  menu  widget 
using  a  Box  widget  that  contains  Label  and  Command  widgets  (as  will  be  demonstrated),  and 
convert  the  application  to  the  R4  menu  widgets  when  you  install  R4.  The  R4  menu  widgets 


*  Under  some  widget  sets  and  window  managers,  menus  don't  even  display  a  title — they  simply  pop  up  at  the  pointer 
position  in  response  to  a  particular  pointer  button/keypress  combination.  This  is  the  behavior  of  the  menus  provided 
by  xterm  and  uwm.  However,  this  is  not  very  desirable  behavior  from  a  user-interface  point  of  view,  since  it  gives  the 
user  no  visual  feedback  that  a  menu  is  available  or  how  to  invoke  it  The  user  needs  the  manual — something  graphi 
cal  user  interfaces  are  designed  to  avoid. 

tTo  be  fair,  there  is  something  to  be  said  for  the  fact  that  all  the  available  commands  are  always  visible  in  an  applica 
tion  that  uses  button  boxes.  You  can  invoke  a  button  in  a  box  with  just  a  button  click,  while  in  a  menu  it  requires  a 
press,  a  drag,  and  a  release.  When  there  are  only  a  small  number  of  commands,  putting  the  command  widgets  in  a 
box  is  probably  better  than  using  a  menu. 
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will  not  work  under  R3,  because  they  depend  on  changes  to  Xt  made  in  R4  (but  most  R3  code 
should  work  under  R4). 


12.1   Menu  Styles  and  Implementation 

The  conventions  for  the  appearance  and  user  interface  of  menus  (look  and  feel)  in  widget  sets 
probably  varies  more  than  any  other  aspect  of  the  user  interface. 

There  are  several  different  styles  of  menus.  As  we've  pointed  out  earlier,  a  button  box  is 
itself  a  style  of  menu.  However,  in  this  chapter,  we  will  be  focusing  on  pop-up 
menus — menus  that  are  not  visible  until  the  user  presses  a  pointer  button  or  a  key-button 
combination. 

There  are  several  different  styles  of  pop-up  menu.  Probably  the  most  familiar  is  the  pull 
down  menu  popularized  by  the  Apple  Macintosh.  A  pull-down  menu  has  a  label  permanently 
visible  in  the  application,  usually  on  a  menu  bar  at  the  top.  When  the  pointer  is  clicked  on 
the  label,  and  then  dragged  downwards,  the  menu  is  pulled  down  like  a  window  shade,  and 
remains  displayed  as  long  as  the  pointer  button  is  depressed.  The  currently  selected  item  (as 
indicated  by  the  pointer  position  within  the  menu)  is  highlighted,  and  is  executed  when  the 
pointer  button  is  released. 

The  variation  adopted  by  both  Motif  and  OPEN  LOOK  (possibly  to  avoid  legal  entanglements 
with  Apple)  is  the  drop-down  menu.  The  pointer  need  not  be  dragged  down  to  display  the 
menu.  Instead,  it  appears  to  drop  down  as  soon  as  the  button  is  depressed  in  the  menu  title. 
(Actually,  it  doesn't  drop  down  at  all,  but  simply  pops  up  below  the  menu  title.)  The  distinc 
tion  between  pull-down  and  drop-down  menus  is  a  subtle  one,  since  with  a  drop-down  menu 
the  pointer  must  subsequently  be  dragged  down  the  menu  in  order  to  make  a  selection. 

In  some  cases,  selecting  an  item  on  the  menu  or  moving  off  the  right  side  of  certain  menu 
panes  causes  a  second  menu  to  appear  next  to  the  first  (usually  to  the  right).  This  is  referred 
to  as  a  cascading  pop  up. 

Finally,  there  is  the  pure  spring-loaded  pop-up  menu  used  by  many  of  the  standard  X  clients, 
which  displays  no  menu  label,  and  simply  pops  up  at  the  pointer  position,  given  the  appropri 
ate  key  or  button  press. 

For  example,  the  menus  in  xterm  pop  up  when  you  hold  the  Control  key  and  press  the  first  or 
second  button  while  the  pointer  is  anywhere  in  the  xterm  window. 

One  can  also  imagine  many  other  possible  menu  styles.  For  example,  an  effective  user 
interface  could  be  constructed  using  only  pop-up  button  boxes,  emulating  the  single-line 
menu  popularized  by  Lotus  for  its  character-based  123  spreadsheet.  Any  given  button  might 
either  execute  an  action,  or  pop  up  a  lower-level  menu,  which  would  overlay  (and  thus 
appear  to  replace)  the  first  menu. 

In  this  chapter,  though,  we  will  focus  on  the  two  styles  of  menu  you  are  most  likely  to 
encounter  in  X  applications:  the  drop-down  menu  and  the  pure  spring-loaded  pop  up. 
(Though  a  drop-down  menu  is  technically  also  a  spring-loaded  pop  up,  throughout  the  rest  of 
this  chapter,  we  will  use  the  latter  term  to  refer  to  an  unlabeled,  position-independent  pop-up 
menu  such  as  that  used  by  xterm.) 
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The  difference  between  spring-loaded  and  drop-down  menus  is  primarily  in  the  method  of 
placing  the  menu  before  popping  it  up;  one  menu  widget  class  can  usually  work  in  either 
style. 

To  be  precise,  the  Xt  specification  makes  the  distinction  between  modeless  pop  ups,  modal 
pop  ups,  and  spring-loaded  pop  ups. 

Modeless  pop  ups  are  windows  that,  once  popped  up,  are  subject  to  window  manager  control, 
and  for  all  intents  and  purposes  act  like  regular  applications  in  themselves.  A  help  window 
that  stayed  up,  and  could  be  moved  and  resized  like  a  regular  window  once  popped  up  is  an 
example  of  this  type  of  pop  up.  It  is  referred  to  as  "modeless"  because  it  doesn't  put  the 
application  into  a  special  mode,  in  which  only  input  to  the  pop  up  is  allowed. 

A  modal  pop  up  may  or  may  not  be  visible  to  the  window  manager,  and  disables  user-event 
processing  by  the  application,  except  in  the  pop  up  itself.  A  dialog  box  that  requires  the  user 
to  enter  data  or  click  on  a  button  is  an  example  of  a  modal  pop  up.  Typically,  input  may  still 
be  possible  to  other  applications. 

A  spring-loaded  pop  up,  as  defined  by  Xt,  is  invisible  to  the  window  manager,  and  disables 
user  input  to  all  windows,  except  to  the  pop  up  itself.  The  most  important  thing  about  spring- 
loaded  pop  ups  is  that  they  are  invoked  with  a  key  or  pointer  button  press,  whereas  another 
type  of  pop  up  might  be  invoked  as  a  routine  part  of  application  processing,  or  just  because 
the  pointer  entered  a  particular  window. 

However,  due  to  a  lack  of  appropriate  terminology,  throughout  this  chapter  we  use  the  term 
"spring-loaded  pop  up"  to  refer  to  menus  that  pop  up  at  the  pointer  position  when  a  button  is 
pressed,  as  opposed  to  drop-down  or  pull-down  menus. 

1 2.1 .1    How  Menus  are  Popped  Up 

How  you  create  menus  in  an  application  differs  according  to  the  class  of  menu  widget  and 
whether  it  will  be  drop-down  or  spring-loaded.  Commercial  widget  sets  are  designed  to 
make  it  quite  easy  to  create  menus  that  fit  into  their  user-interface  conventions.  As  usual,  the 
examples  in  this  chapter  use  the  Athena  widgets  to  implement  various  types  of  menus. 
Although  the  procedure  for  creating  menus  under  the  widget  set  you  plan  to  use  may  be  dif 
ferent,  many  of  the  underlying  issues  are  the  same. 

In  Section  3.3,  a  dialog  pop  up  was  created  by  first  creating  a  pop-up  shell,  and  then  creating 
the  widget  to  be  popped  up  as  a  child  of  the  pop-up  shell.  This  procedure  is  used  for  some 
menu  widgets,  but  most  menu  widgets  are  themselves  subclasses  of  Shell,  and  therefore  no 
separate  shell  needs  to  be  created.  You  just  create  an  instance  of  the  menu  widget  itself, 
using  XtCreatePopupShell  instead  of  XtCreateManagedWidget. 

To  have  a  spring-loaded  pop  up,  your  application  usually  adds  an  action  that  places  the 
widget  in  the  application  main  window.  (Xt  has  a  standard  action  for  popping  up  a  widget, 
but  by  default  it  places  the  widget  at  the  top-left  corner  of  the  screen.  As  a  result,  you  must 
use  it  in  conjunction  with  an  action  of  your  own,  which  moves  the  invisible  shell  widget  to 
the  desired  location  before  it  is  actually  popped  up.)  The  application-defaults  file  should 
supply  a  translation  to  specify  what  event  sequence  will  call  up  that  menu. 
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In  some  cases,  a  menu  widget  itself  may  add  actions  and  translations  to  the  parent  so  that  the 
widget  can  be  popped  up  in  spring-loaded  fashion  without  any  application  code.  In  others, 
the  widget  will  add  the  actions  but  leave  the  user  or  the  application  writer  to  define  the  trans 
lation  that  will  invoke  the  action. 

To  use  a  menu  in  drop-down  fashion,  you  create  a  Command  widget  and  use  its  callback  to 
pop  up  the  menu,  or  better  still,  use  a  widget  specially  made  to  invoke  a  drop-down  menu, 
and  tell  it  the  name  of  the  shell  to  be  popped  up  (which  as  just  mentioned  may  be  the  menu 
widget  itself). 

Menus  differ  widely  on  their  conventions  for  when  to  pop  down.  Most  menus  pop  down  after 
a  choice  is  made.  In  this  case,  the  callback  invoked  to  tell  the  application  about  the  menu 
choice  would  pop  down  the  widget,  or  perhaps  the  menu  widget  itself  would  pop  itself  down 
before  calling  the  chosen  item's  callback.  Some  menus  pop  down  whenever  the  button  that 
popped  them  up  is  released  (for  example,  xterm),  even  if  the  pointer  is  outside  the  menu 
when  the  button  is  released.  Some  pop  down  whenever  the  pointer  moves  out  of  the  menu 
(for  example,  uwm)*  OPEN  LOOK  menus  provide  a  pushpin  metaphor  that  allows  the  user  to 
keep  a  pop-up  menu  on  the  screen,  where  it  will  be  handy  for  repeated  use. 


12.1.2   Menu  Panes 


The  style  of  the  items,  or  panes,  in  the  menus  also  varies  widely.  Panes  are  usually  imple 
mented  using  one  or  more  subwidgets,  or  in  the  case  of  Motif  and  the  Athena  SimpleMenu 
widget,  with  gadgets,  which  are  windowless  objects  that  can  be  drawn  and  managed  sepa 
rately  within  a  widget  There  may  be  several  different  widgets  or  gadgets  that  implement 
menu  panes  with  different  input  and  output  semantics. 

If  the  panes  are  widgets,  they  are  created  with  xtCreateManagedWidget,  or  in  some 
menu  widgets,  by  specifying  resources  of  the  menu  widget,  which  will  then  create  its  own 
panes;  how  gadgets  are  created  is  discussed  later  in  this  chapter. 

Figure  12-2  shows  menus  developed  using  OSF's  Motif  and  AT&T's  OPEN  LOOK  Toolkit, 
which  you  can  compare  and  contrast  with  each  other  and  with  the  R4  Athena  SimpleMenu 
widget  shown  in  Figure  12-1. 


*Most  people  find  it  annoying  to  have  menus  that  pop  down  when  the  pointer  moves  out  of  them.  It  is  too  easy  to  ac 
cidentally  move  outside  the  menu  and  have  to  start  all  over.  All  the  menus  in  this  chapter  pop  down  the  menu  when 
the  choice  is  made,  or  when  the  button  is  released  outside  the  menu. 
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Figure  12-2.  Menus  from  the  OPEN  LOOK  and  Motif  widget  sets 

The  Athena  SimpleMenu  widget  has  rectangular  panes  that  display  an  identifying  string,  and 
an  optional  bitmap  before  and/or  after  the  string.  For  example,  the  bitmap  can  be  used  to 
place  a  checkmark  to  the  left  of  the  label  (indicating  that  an  option  has  been  selected  and  is 
in  effect),  or  an  arrow  to  the  right,  indicating  that  selecting  this  pane  will  produce  a  cascad 
ing  submenu.  When  an  item  is  selected,  it  is  displayed  in  inverse  video. 

Motif  menu  panes  are  rectangular.  The  currently-selected  pane  is  highlighted  with  a  simu 
lated  3-D  shadow.  Panes  may  contain  either  a  string  or  a  bitmap. 

OPEN  LOOK  menus  come  with  several  types  of  panes,  depending  on  the  type  of  menu  item. 
Commands,  whether  available  from  menus,  or  in  other  control  areas,  are  represented  by 
oblong  buttons  with  rounded  ends.  (Buttons  that  generate  menus  (or  submenus)  follow  their 
label  with  an  arrowhead  pointing  in  the  direction  where  the  submenu  will  appear.)  Exclusive 
options  are  shown  as  adjacent  rectangles,  with  the  one  currently  chosen  highlighted  by  a  dark 
border.  Nonexclusive  options  are  displayed  in  rectangles  with  a  small  separation  between 
each  one.  Panes  may  contain  a  string  or  a  bitmap,  or  both. 

However,  what  all  menu  widgets  have  in  common  is  that  the  application  programmer  can  set 
the  label  of  each  pane  and  the  function  it  invokes.  Exactly  how  to  do  this  varies  according  to 
the  widget  set  you  use. 
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See  Appendix  A,  OPEN  LOOK  and  Motif,  for  more  information  on  how  Motif  and  OPEN 
LOOK  implement  menus. 


12.2  Several  Ways  to  Create  and  Use  Menus 


You  already  know  how  to  create  a  pop-up  shell,  create  a  Box  as  its  child,  fill  it  with  Com 
mand  widgets,  label  the  Command  widgets,  and  register  a  callback  function  for  each  one.  By 
doing  this  you  can  create  a  basic  menu.  Its  performance  is  rather  sluggish,  but  it  looks  and 
works  like  a  menu  and  is  the  best  you  can  do  with  the  R3  Athena  widgets  without  writing  a 
menu  widget  of  your  own.  If  you  are  using  the  R3  Athena  widgets,  you  can  use  this  tech 
nique  until  you  have  access  to  the  R4  Athena  SimpleMenu  widget  or  one  of  the  commercial 
widget  sets. 

This  section  describes  how  to  use  the  menu  made  from  a  box  full  of  buttons  in  two  different 
menu  styles:  spring-loaded  and  drop-down.  The  purpose  of  this  exercise  is  to  expose  some 
of  the  issues  involved  in  event-management  of  pop  ups.  Some  of  these  issues  may  be  hidden 
in  the  widgets  or  facilities  provided  by  some  commercial  widget  sets,  but  seeing  how  to  do 
the  event  management  explicitly  should  help  you  to  understand  and  use  pop  ups  more  effec 
tively. 

The  challenge  of  creating  a  pop  up  with  Box  and  Command  buttons  is  to  make  it  pop  up  and 
down  at  the  right  times,  and  to  control  its  event  handling  to  fit  the  menu  style.  We  will  also 
experiment  with  creating  a  cascaded  menu,  in  which  one  menu  pane  in  a  main  menu  invokes 
a  submenu. 

Finally,  this  section  describes  how  to  create  a  menu  using  the  R4  SimpleMenu  widget  and  its 
gadget  children. 

12.2.1    A  Spring-Loaded  Menu:  Pointer  Grabbing 

A  spring-loaded  menu  should  pop  up  when  a  button  press  occurs  in  a  particular  widget; 
usually  the  application's  main  window.  The  menu  should  stay  visible  as  long  as  the  user 
holds  down  that  button,  and  disappear  when  the  button  is  released.  If  the  button  is  released  in 
a  menu  pane,  the  function  registered  for  that  pane  should  be  invoked.  If  the  button  is 
released  outside  the  menu,  no  function  should  be  invoked  but  the  menu  should  still  be 
popped  down. 

The  only  tricky  part  of  implementing  a  spring-loaded  menu  is  getting  the  menu  to  pop  down 
when  the  button  is  released  outside  the  menu.  Since  this  occurs  outside  the  menu  and  possi 
bly  outside  the  application,  the  X  server  will  not  send  the  button  release  event  to  the  applica 
tion  unless  a  grab  is  in  effect.  Normally,  user  events  are  sent  to  the  window  that  contains  the 
pointer.  But  after  an  application  makes  a  grab,  the  X  server  sends  all  events  of  particular 
types  to  the  window  that  made  the  grab,  even  if  the  pointer  is  no  longer  in  the  window. 

The  X  server  defines  several  types  of  grab:  keyboard  grabs,  pointer  grabs,  and  server  grabs. 
Keyboard  and  pointer  grabs  control  only  input  from  the  indicated  device,  while  server  grabs 
make  the  server  act  on  requests  from  one  application  exclusively.  (Server  grabs  are  mainly 
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used  by  window  managers.)  Pointer  grabs  are  used  for  controlling  events  in  pop  ups  when  a 
pointer  button  pops  up  the  pop  up,  and  keyboard  grabs  are  used  when  a  key  press  pops  up  the 
pop  up.  We  will  discuss  pointer  grabs  since  keyboard  grabs  are  analogous  (and  keyboard- 
triggered  pop  ups  are  less  common). 

There  are  two  types  of  pointer  grabs,  passive  grabs  and  active  grabs.  An  active  grab  is 
invoked  directly  with  the  Xlib  function  XGrabPo inter.  This  function  tells  the  server  that 
you  want  the  grab  to  begin  right  away,  and  to  continue  until  specifically  released  with 
XUngrabPointer.  Active  grabs  are  not  normally  used  for  pop  ups.* 

A  passive  grab  tells  the  server  that  you  want  a  grab  to  begin  when  a  certain  key  or  button 
combination  is  pressed  in  a  certain  window  (the  combination  that  is  to  pop  up  the  pop  up). 
The  grab  continues  until  the  button  in  the  combination  is  released.  This  is  perfect  for  menus 
because  we  need  the  grab  only  until  the  button  is  released.  (Also,  as  you'll  see  in  the  section 
on  drop-down  menus,  you  can  register  several  passive  grabs  for  the  same  key-button  combi 
nation  as  long  as  each  grab  is  initiated  by  a  press  in  a  different  window.  This  allows  you  to 
have  as  many  drop-down  menus  as  you  want.  Since  spring-loaded  pop  ups  are  generally 
invoked  by  a  press  in  the  same  window — the  application  main  window — you  will  need  to 
use  a  different  key-button  combination  for  each  different  menu.) 

Xt  provides  three  ways  of  popping  widgets  up  and  down: 

•  There  are  three  built-in  callback  functions:    xtCallbackNone,  xtCallback- 
Exclusive,  and  XtCallbackNonexclusive.    Each  of  these  functions  pops  up  a 
widget  with  a  different  type  of  grab,  as  indicated  by  its  name.   XtCallbackNone 
makes  no  grab  at  all.   The  difference  between  an  exclusive  grab,  as  caused  by  xt- 
CallbackExclusive,  and  a  nonexclusive  grab,  as  caused  by  XtCallback 
Nonexclusive,  has  to  do  with  the  handling  of  cascading  widgets.  In  brief,  an  exclu 
sive  grab  constrains  input  to  the  widget  actually  making  the  grab  (the  latest  widget  in  the 
cascade),  while  a  nonexclusive  grab  allows  input  to  any  widget  in  the  cascade.  We'll  talk 
more  about  this  in  Section  12.2.3,  when  we  talk  about  pop-up  cascades. 

XtCallbackPopdown  is  the  corresponding  built-in  callback  function  to  pop  down  a 
widget. 

•  There  are  two  built-in  actions,  MenuPopup  and  MenuPopdown,  that  pop  up  or  pop 
down  a  widget  You  can  use  these  actions  in  translation  tables  in  the  application-defaults 
file  or  application  code.  MenuPopup  always  asserts  an  exclusive  grab. 

•  There  are  two  functions,  xtPopup  and  XtPopdown,  that  you  can  call  directly  in  your 
application  code  to  pop  up  or  pop  down  a  widget.  Xt  Popup  has  a  grab_kind  argu 
ment  that  lets  you  specify  whether  to  assert  an  exclusive  or  nonexclusive  grab,  or  no  grab. 

Each  of  these  ways  is  appropriate  for  different  situations,  and  they  are  often  used  in  combina 
tion.  Each  will  be  described  in  the  sections  below. 


*One  reason  that  XGrabPo  inter  is  rarely  used  for  pop  ups  is  that  it  requires  that  the  window  that  will  receive  the 
grabbed  events  be  visible.  This  is  often  not  the  case.  In  a  menu,  for  example,  the  window  that  you  want  to  grab  the 
events  is  hidden  by  the  menu  panes  even  when  the  menu  is  popped  up.  Another  reason  is  that  you  need  to  call 
XUngrabPointer  to  release  the  grab  when  finished.  Passive  grabs  match  the  task  better. 


352  X  Toolkit  Intrinsics  Programming  Manual 


Passive  grabs  can  be  invoked  directly  using  the  Xlib  functions  XGrabButton  and 
XGrabKey.  However,  Xt  takes  care  of  making  the  appropriate  passive  grab  if  you  use  the 
MenuPopup  action  to  pop  up  your  shell  widget.  As  we  will  see,  the  other  two  ways  to  pop 
up  a  widget  do  not  make  any  grab,  which  makes  them  inappropriate  for  popping  up  main 
menus.  However,  they  are  still  useful  for  some  types  of  dialog  boxes  and  for  cascading  sub 
menus,  if  the  main  menu  has  used  MenuPopup  to  assert  an  exclusive  grab.  We'll  return  to 
this  subject  in  Section  12.2.3.* 

A  pop-up  menu  grabs  the  pointer  to  force  the  user  to  make  a  menu  choice  before  leaving  the 
menu,  or  to  pop  down  the  menu  if  no  choice  is  made.  However,  this  grab  is  necessary  for 
another  reason  as  well.  The  X  server  automatically  grabs  the  pointer  beginning  at  a  button 
press  and  ending  at  the  release  of  the  same  button.  Since  the  initial  button  press  pops  up  the 
menu,  the  next  button  release  would  also  arrive  at  the  same  widget — the  application  main 
window — even  if  the  pointer  were  already  in  the  menu.  Furthermore,  the  application  main 
window  would  get  all  EnterNotify  and  LeaveNotify  events,  so  the  Command  wid 
gets  in  the  menu  wouldn't  get  any  of  them.  When  the  menu  is  popped  up  with  MenuPopup 
action,  this  cancels  the  automatic  grab.  (Of  course,  pointer  grabs  redirect  only  the  events 
caused  directly  by  the  pointer;  ButtonPress,  ButtonRelease,  EnterNotify, 
LeaveNotify,  and  MotionNotify.  All  other  events  (most  notably  Expose  events) 
occur  and  are  delivered  normally.) 

With  that  background,  let's  take  a  look  at  an  application  that  provides  a  spring-loaded  menu. 
The  xmenul  application's  permanent  appearance  is  a  variation  of  xbox\  it  displays  a  large 
Label  widget  that  we  are  using  to  simulate  an  application's  main  window  and  a  Command 
widget  for  quitting.  Pressing  any  button  in  the  Label  widget  calls  up  the  menu,  which  oper 
ates  as  described  at  the  beginning  of  this  section,  xmenul  is  shown  in  Figure  12-3.  As  usual, 
we  suggest  you  compile  and  run  this  example  now. 


*XtPopup,  XtCallbackExclusive,  and  XtCallbackNonexclusive  in  fact  make  no  grab  at  all.  As 
we  will  see,  this  is  needed  to  make  them  useful  for  submenus,  and  they  are  also  useful  for  dialog  boxes.  In  R4,  a  new 
function  called  XtPopupSpringLoaded  has  been  added  as  a  version  of  XtPopup  that  does  make  a  passive 
grab.  Since  all  R4  changes  are  backwards  compatible  with  R3,  the  XtCallback*  callback  functions  have  not 
been  changed  and  will  still  not  be  useful  for  menus  (although  they  will  still  be  useful  for  some  dialog  boxes).  With 
XtPopupSpringLoaded  you  can  also  write  callback  functions  that  are  the  equivalent  of  XtCallback*,  ex 
cept  that  they  will  pop  up  a  menu  with  a  passive  grab. 
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This  is  a  Pretend  Main  LJlndr"--*  P*~ 


MAIN  MENU 


View  Next 
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Figure  12-3.  xmenul:  application  with  spring-loaded  pop-up  menu 

The  relevant  code  in  xmenul  consists  of  an  action  routine  to  place  the  pop  up,  code  to  add  the 
action,  a  callback  routine  to  handle  when  a  menu  item  has  been  chosen,  and  code  to  create 
the  Box  populated  with  Command  widgets  that  will  act  as  the  menu.  Example  12-1  shows 
the  complete  code. 

Example  12-1.  xmenul:  complete  code 

I  * 

*  xmenul. c  -  simple  spring-loaded  menu 
*/ 

/* 

*  So  that  we  can  use  fprintf: 

*/ 

tinclude  <stdio.h> 

/* 

*  Standard  Toolkit  include  files: 
*/ 

tinclude  <Xll/Intrinsic.h> 
tinclude  <Xll/StringDef s .h> 

tinclude  <Xll/Shell .h> 

/* 

*  Public  include  files  for  widgets  used  in  this  file. 
*/ 

tifdef  X11R3 

tinclude  <X11 /Command. h> 
tinclude  <Xll/Box.h> 
tinclude  <Xll/Label .h> 
telse  /*  R4  or  later  */ 
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Example  12-1.  xmenul:  complete  code  (continued) 

#include  <Xll/Xaw/Command.h> 
#include  <Xll/Xaw/Box.h> 
finclude  <Xll/Xaw/Label .h> 
#endif  /*  X11R3  */ 

The  popup  shell  ID  is  global  because  both  dialog  and  pshell 
are  needed  in  the  dialogDone  callback,  and  both  can't  be 
passed  in  without  creating  a  structure. 
i 

Widget  pshell; 

void  PlaceMenu (w,  event) 
Widget  w; 
XButtonEvent  *event; 

Arg  args [  5  ]  ; 

int  i; 

/*  should  make  sure  coordinates  let  menu  fit  on  screen  */ 

/* 

*  move  submenu  shell  slightly  to  left  and  above  button 

*  position 
*/ 

i  =  0; 

XtSetArg(args [i] ,  XtNx,  event->x_root  -  10); 
XtSetArg(args[i] ,  XtNy,  event->y_root  -  10); 
XtSetValues (pshell,  args,  i) ; 


/* 

*  guit  button  callback  function 

*/ 

void  Quit  (w,  client_data,  call_data) 
Widget  w; 

caddr_t  client_data,  call_data; 
{ 

exit  (0)  ; 


/* 

*  menu  pane  button  callback  function 

*/ 

void  PaneChosen  (w,  pane_number,  call_data) 
Widget  w; 

int  pane_number;   /*  client_data  */ 
caddr_t  call_data; 

printf  ("Pane  %d  chosen.  \n",  pane_number)  ; 
XtPopdown  (pshell)  ; 


main(argc,  argv) 
int  argc; 
char  **argv; 
{ 

Widget  topLevel,  box,  label,  guit,  menubox, 
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Example  12-1.  xmenul:  complete  code  (continued) 

menulabel,    menupane [ 10] ; 
int    i; 
String   buf [50] ; 

static   XtActionsRec   trial_actions [ ]    =    { 
{"placeMenu",    PlaceMenu}, 

}; 

topLevel  =  Xtlnitialize ( 

argv[0],  /*  application  name  */ 

"XMenul",  /*  application  class  name  */ 

NULL,  /*  application  resources  (not  used) 

0,  /*  application  resource  count  */ 

&argc,  /*  command  line  argument  count  */ 

argv) ;  /*  command-line  string  */ 

box  =  XtCreateManagedWidget ( 

"box",  /*  widget  name   */ 

boxWidgetClass,      /*  widget  class  */ 

topLevel,  /*  parent  widget*/ 

NULL,  /*  argument  list*/ 

0  /*  arglist  size  */ 

label  =  XtCreateManagedWidget ( 

"label",  /*  widget  name  */ 

labelWidgetClass,    /*  widget  class  */ 
box,  /*  parent  widget*/ 

NULL,  /*  argument  list*/ 

0  /*  arglist  size  */ 

quit  =  XtCreateManagedWidget ( 

"quit",  /*  widget  name  */ 

commandWidgetClass,  /*  widget  class  */ 
box,  /*  parent  widget*/ 

NULL,  /*  argument  list*/ 

0  /*  arglist  size  */ 

pshell  =  XtCreatePopupShell ( 
"pshell", 

transient ShellWidget Class, 
topLevel, 
NULL, 
0 
); 

menubox  =  XtCreateManagedWidget ( 

"menubox",  /*  widget  name   */ 

boxWidgetClass,      /*  widget  class  */ 
pshell,  /*  parent  widget*/ 

NULL,  /*  argument  list*/ 

0  /*  arglist  size  */ 


menulabel  =  XtCreateManagedWidget ( 

"menulabel",         /*  widget  name  */ 
labelWidgetClass,    /*  widget  class  */ 
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Example  12-1.  xmenul:  complete  code  (continued) 

menubox,  /*    parent   widget*/ 

NULL,  /*    argument    list*/ 

0  /*   arglist   size    */ 

for  (i  =  0;  i  <  10;  i++)  { 

sprintf(buf,  "menupane%d",  i) ; 

menupane[i]  =  XtCreateManagedWidget (buf ,    /*  widget  name  */ 
commandWidgetClass,  menubox,  NULL,  0) ; 

XtAddCallback (menupane[i] ,  XtNcallback,  PaneChosen,  i)  ; 

XtAddActions (trial_actions,  XtNumber (trial_actions) ) ; 
XtAddCallback (quit,  XtNcallback,  Quit,  0); 
XtRealizeWidget (topLevel)  ; 
XtMainLoop ( ) ; 

The  PlacePopup  action  just  places  the  pop  up  slightly  to  the  left  and  above  the  position 
where  the  pointer  button  that  popped  it  up  was  clicked,  using  the  coordinates  reported  in  the 
button  event.  The  offset  of  ten  pixels  from  the  pointer  position  simply  helps  to  make  sure 
that  the  pointer  is  inside  the  menu.*  Remember  that  the  window  created  by  a  pop-up  shell 
widget  is  a  child  of  the  root  window  and  therefore  is  placed  relative  to  the  root  window.  The 
ButtonPress  event  pointer  coordinates  relative  to  the  root  window  are  used. 

The  PaneChosen  callback  function  is  a  stub  function  used  in  this  example  as  the  notify 
callback  for  all  the  menu  panes.  In  this  example,  it  simply  prints  the  name  of  the  chosen  pane 
to  stdout  and  then  pops  down  the  menu  using  XtPopdown.  In  a  real  application,  a  different 
callback  function  would  probably  be  registered  for  each  pane. 

Instead  of  calling  XtPopdown  in  each  of  these  separate  callback  functions,  you  could  write 
a  single  additional  callback  function  that  calls  xtPopdown,  and  then  add  it  to  the  callback 
list  for  the  Command  widget  that  makes  up  each  menu  pane. 

As  usual,  the  pop  up  is  created  by  first  creating  a  pop-up  shell,  then  a  Box  widget  as  its  child, 
and  then  a  series  of  Label  and  Command  widgets  as  children  of  Box.  The  pop-up  shell  is 
itself  invisible.  As  with  all  menus,  what  you  actually  see  is  the  array  of  children. 

Note  that  this  program  does  not  include  any  code  that  would  pop  up  the  menu.  We've  done 
that  from  the  application-defaults  file  shown  in  Example  12-2.  The  translations  for  the  Label 
widget  invoke  Xt's  built-in  MenuPopup  action. 


*It  is  important  to  provide  a  consistent  user  interface,  so  you  should  use  the  same  offset  in  all  menus.  Menus  in  com 
mercial  widget  sets  such  as  the  OPEN  LOOK  widgets  have  carefully  designed  and  documented  policies  about  pop-up 
window  placement.  This  allows  the  user's  "pointer  reflexes"  to  be  trained,  so  that  using  menus  becomes  as  automatic 
and  easy  as  possible. 
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Example  12-2.  XMenul:  the  application-defaults  file 

i 

!  Appearance  Resources 

i 

*quit. label:   Quit 

*label . label :  This  is  a  Pretend  Main  Window;  Press  in  here. 

*menulabel. label:  FILE  MENU 

i 

!  make  all  entries  in  menu  same  width  (adjust  value  for  longest  entry) 
i 

*menulabel .width:  80 
*menubox . Command. width:   80 
*menupaneO . label :   Create 
*menupanel . label :   Open 
*menupane2 . label :   Delete 
*menupane3 . label :   Rename 

*menupane4 . label :   Copy 
i 

!  make  Box  leave  no  space  around  Command  widgets  in  menu 
i 

*pshell .Box .hSpace :  0 
*pshell .Box . vSpace :  0 
i 

!  Translation  Resources 

i 

*menubox . Command . translations : \ 

<EnterWindow>:      highlight ()  \n\ 

<LeaveWindow> :      reset ()  \n\ 

<BtnUp>:  set()  notify ()  unset  () 

*  label .translations : \ 

<BtnDown>:  placeMenu()  MenuPopup (pshell) 
* pshell . translations : \ 

<BtnUp> :  MenuPopdown (pshell) 

There  are  a  number  of  settings  designed  to  give  the  Box  widget  a  characteristic  menu  appear 
ance:  all  of  the  Command  widgets  are  forced  to  have  the  same  size  (rather  than  the  size  of 
their  label),  and  the  Box  widget  is  forced  to  leave  no  space  between  the  command  widgets. 

However,  it  is  the  new  translations  that  are  the  critical  part  of  this  application-defaults  file. 
The  Label  widget  must  be  given  translations  so  that  a  button  press  will  pop  up  the  widget. 
The  supplied  translation  maps  a  button  press  into  a  call  to  the  application  action  Place- 
Popup  and  then  to  Xt's  predefined  MenuPopup  action.  The  argument  to  MenuPopup  in 
the  translation  is  the  instance  name  of  the  pop-up  shell.  Xt  converts  this  string  name  into  the 
widget  ID  of  the  pop-up  shell  before  it  can  pop  up  the  widget 

We  are  replacing  rather  than  overriding  this  widget's  translations  because  it  is  a  Label  widget 
and  has  no  default  translations. 

The  menu  panes  are  Command  widgets,  but  we  need  to  adjust  their  event  response  so  that 
they  will  be  triggered  on  a  button  release  with  no  corresponding  press  (since  the  press  that 
popped  up  the  menu  occurred  in  the  application  main  window).  We  are  replacing  their  trans 
lations  to  get  rid  of  the  translation  for  ButtonPress  (which  would  still  be  present  if  we 
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used  the  # augment  directive,  and  we  would  have  to  create  an  action  that  did  nothing  in 
order  to  replace  it  with  tfoverride).  The  translation  for  ButtonRelease  (BtnUp  in 
the  translation  table)  calls  all  the  actions  that  usually  occur  in  Command  widgets  with  both 
press  and  release. 

Perhaps  least  obvious  is  the  translation  we  have  added  to  pop  down  the  menu  when  the 
pointer  button  is  released  outside  the  menu.  As  mentioned  earlier,  Xt  makes  a  passive  pointer 
grab  on  the  pop-up  shell  (pshell)  in  the  MenuPopup  action.  When  the  pointer  is  inside 
the  menu,  the  Command  widgets  intercept  these  grabbed  events,  because  they  are  descen 
dants  of  pshell  and  they  have  a  translation  for  ButtonRelease  events.  This  invokes 
the  actions  in  the  selected  Command  widget.  But  when  the  pointer  is  outside  the  menu,  the 
grabbed  events  are  sent  directly  to  the  widget  that  was  specified  in  the  grab  call,  namely 
pshell.  Therefore,  the  translation  to  pop  down  the  menu  on  button  release  must  be  added 
to  pshell.  (Again,  this  translation  table  is  simply  replaced  because  the  pop-up  shell  nor 
mally  has  no  translations.) 


A  Drop-Down  Menu 

What  are  the  desired  characteristics  of  a  drop-down  menu?  There  is  a  Command  widget  or 
the  like  permanently  visible  in  the  application,  with  a  label  indicating  some  common  charac 
teristic  of  the  items  in  the  menu.  When  a  button  is  pressed  in  this  widget,  the  menu  should 
pop  up  on  or  just  below  the  button.  Dragging  the  pointer  down  through  the  menu  with  the 
button  still  held  should  highlight  the  entry  that  is  pointed  to.  Releasing  the  button  in  an  entry 
should  invoke  or  set  that  entry,  and  pop  down  the  menu.  Moving  out  of  the  menu  should  not 
change  this  behavior,  except  that  if  the  button  is  released  anywhere  outside  of  a  menu  pane, 
the  menu  should  pop  down  without  executing  any  entry. 

If  you  compile  and  run  xmenu2  you  can  try  out  this  style  of  menu.  The  appearance  of  this 
application  is  shown  in  Figure  12-4. 


Figure  12-4.  xmenu2:  a  drop-down  menu 
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Invoking  a  menu  as  a  drop-down  is  a  simple  enhancement  of  the  spring-loaded  invocation 
method  just  shown.  We  can  do  everything  exactly  the  same  as  in  the  spring-loaded  example, 
except  that  a  drop-down  menu  should  appear  just  below  the  pressme  widget,  not  at  the 
pointer  position.  Therefore,  all  we  need  to  change  is  the  placement  code.  However,  since  the 
coordinates  in  the  event  are  not  necessary  for  placing  the  pop  ups,  we  can  use  a  callback 
function  instead  of  an  action  to  place  the  pop  up.  (In  general,  it  is  better  to  use  an  existing 
callback  than  to  add  an  action  to  do  the  same  thing.) 

Pop-up  shell  widgets  have  XtNpopupCallback  and  xtNpopdownCallback  callback 
resources;  the  functions  on  these  callback  lists  are  called  whenever  the  pop  up  is  popped  up 
or  down  using  any  of  the  Xt  mechanisms. 

In  the  last  example  we  created  an  action  called  PlaceMenu,  to  move  the  pop-up  shell 
before  it  was  actually  popped  up.  We  included  it  in  a  translation  along  with  the  standard 
action  MenuPopup,  which  was  actually  used  to  pop  up  the  widget.  xmenu2  also  uses  the 
standard  action  MenuPopup  to  pop  up  the  widget,  but  it  uses  the  XtNpopupCallback 
resource  to  invoke  the  code  to  place  it.  This  saves  having  to  reference  the  placement  action 
in  the  translation  table.  This  is  preferable,  since  the  placement  code  should  almost  always  be 
hardcoded  rather  than  user-configurable.  Another  advantage  of  the  pop-up  and  pop-down 
callbacks  is  that  you  may  arrange  for  a  pop  up  to  be  popped  up  or  down  in  more  than  one 
way,  and  it  may  be  convenient  to  have  certain  code  called  automatically  in  all  cases. 

(You  can  also  use  the  XtNpopupCallback  resource  to  specify  a  callback  function  to  cre 
ate  a  pop-up  widget  the  first  time  it  is  popped  up,  instead  of  at  application  startup.  The  one 
problem  is  that  the  functions  on  the  callback  list  are  invoked  every  time  the  widget  is  popped 
up.  To  make  sure  that  it  creates  the  pop  up  only  once  (the  first  time),  the  callback  function 
should  remove  itself  from  the  callback  list  by  calling  XtRemoveCallback.) 

There  is  not  enough  difference  between  xmenul  and  xmenu2  to  merit  showing  the  complete 
code.  All  we  have  done  is  changed  the  PlaceMenu  function  from  an  action  into  a  callback 
and  changed  its  placement  logic  to  place  the  pop-up  relative  to  the  invoking  Command 
widget  We  have  then  modified  the  application-defaults  file  accordingly. 

Example  12-3  shows  the  PlaceMenu  routine  (now  a  callback,  not  an  action)  and  the  code 
to  register  it  as  a  callback. 

Example  12-3.  xmenu2:  code  to  place  drop-down  menu 

void   PlaceMenu (w,    topLevel,    call_data) 

Widget    w; 

Widget  topLevel;  /*  client_data  */ 

caddr_t  call_data; 

{ 

Position  x,  y; 

Arg  arg [2] ; 

int  i; 

int  val; 

/* 

*  Translate  coordinates  of  invoking  Command  widget 

*  into  root  window  coordinates. 
*/ 

XtTranslateCoords (pressme,    /*  Widget  */ 
(Position)  0,         /*  x  */ 
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Example  12-3.  xmenu2:  code  to  place  drop-down  menu  (continued) 

(Position)  0,         /*  y  */ 

&x,  &y) ;  /*  coords  on  root  window  */ 

/* 

*  Move  pop-up  shell  so  that  it  completely  covers  invoking 

*  button,  assuming  border  width  of  1  (menu  not  visible  yet) 
*/ 

i  =  0; 

XtSetArg(arg[i] ,    XtNx,    x    -    1); 
XtSetArg(arg[i] ,    XtNy,    y    -    1); 
XtSetValues (pshell,    arg,    i) ; 
} 

main (argc,    argv) 
int    argc; 
char    **argv; 


XtAddCallback (pshell,    XtNpopupCallback,    PlaceMenu,    topLevel) 


Xt  calls  the  functions  on  the  XtNpopupCallback  list  before  it  pops  up  the  widget.  This 
means  that  PlaceMenu  is  called  before  the  MenuPopup  action,  placing  the  widget  before 
it  is  popped  up. 

Note  that  the  xtTranslateCoords  routine  determines  the  root  window  coordinates  at 
the  origin  of  the  pressme  widget.  Because  of  the  reparenting  done  by  most  window  man 
agers,  this  information  cannot  be  obtained  by  using  xtGetValues  to  read  the  XtNx  and 
XtNy  resources.* 

Example  12-4  shows  the  translation  portion  of  the  application-defaults  file. 

Example  12-4.  XMenu2:  translation  portion  of  the  application-defaults  file 

i 

!  Translation  resources 
i 

*pressme . translations : \ 

<EnterWindow>:      highlight ()  \n\ 

<LeaveWindow> :      reset  ()  \n\ 

<BtnDown>:          set()  MenuPopup (pshell)  reset  () 

l 

*pshell .translations : \ 

<BtnUp>:  MenuPopdown (pshell) 


*Incidentally,  XTranslateCoordinates,  the  Xlib  equivalent  of  XtTranslateCoords,  gets  the  same  in 
formation  and  a  little  more  by  querying  the  server.  XtTranslatCoords  does  not  have  to  make  a  server  request 
because  Xt  stores  this  data  locally.  Each  time  a  window  in  this  application  is  moved,  Xt  receives  this  information  as 
an  event  and  updates  its  knowledge  of  the  position  of  each  window.  This  is  an  important  optimization,  because 
server  queries  are  subject  to  network  delays  and  tend  to  slow  applications. 
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Example  12-4.  XMenu2:  translation  portion  of  the  application-defaults  file  (continued) 

*menubox . Command . translations : \ 

<EnterWindow>:      set()  \n\ 

<LeaveWindow> :      unset  ()  \n\ 

<BtnUp>:  notify ()  unset () 

These  translations  are  different  from  those  forxmenul  only  in  that  pressme  is  a  Command 
widget,  which  already  has  its  own  translation  table,  rather  than  a  widget  without  existing 
translations.  We  have  modified  the  translations  of  pressme  to  be  suitable  for  this  use. 
Note  that  the  translation  no  longer  calls  PlaceMenu  as  an  action  because  it  is  now  a  call 
back. 

The  translations  for  the  menu  pane  Command  widgets  are  also  somewhat  different  from 
xmenul,  but  only  for  cosmetic  reasons.  This  iteration  of  the  xmenu  example  uses  the  set 
and  unset  actions  instead  of  highlight  and  reset  or  unhighlight  to  make  the 
Command  widgets  highlight  their  entire  box  instead  of  just  an  area  near  the  border. 
(Although  this  modification  makes  the  menu  look  more  like  a  typical  menu,  it  also  seems  to 
make  it  slower.) 

To  create  several  menus  you  simply  need  to  replicate  the  code  shown  here,  changing  the  vari 
able  names  for  each  menu.  The  passive  grabs  invoked  by  Xt  for  each  menu  do  not  interfere 
with  each  other  even  if  they  specify  the  same  key/button  combination,  because  they  specify 
different  windows  in  which  the  key/button  combination  will  begin  the  grab. 

12.2.3   Cascaded  Menus 

A  cascaded  menu  is  a  menu  in  which  one  or  more  panes  do  not  invoke  functions  but  instead 
bring  up  additional  menus. 

The  techniques  used  to  bring  up  cascaded  menus  can  also  be  used  to  have  dialog  boxes  bring 
up  other  dialog  boxes.  However,  cascaded  menus  are  more  challenging  because  they  rely  on 
the  passive  pointer  grab  to  receive  the  ButtonRelease  event  that  occurs  outside  the 
menu  and  application. 

You  can  implement  a  cascaded  menu  the  same  way  for  both  spring-loaded  and  drop-down 
menus,  simply  by  adding  to  the  code  we've  already  written  to  implement  a  single  menu. 
We'll  show  you  xmenuS,  the  spring-loaded  version,  since  it  is  slightly  shorter.  (xmenu4  is  the 
equivalent  drop-down  version.)  Both  are  included  in  the  example  source  code.  In  this 
example,  only  one  menu  pane  will  be  used  to  invoke  a  submenu.  However,  this  technique 
can  be  generalized  to  have  additional  panes  bring  up  additional  submenus. 

First,  let's  describe  exactly  how  we  expect  the  cascaded  menu  to  work.  Figure  12-5  shows 
both  menus  popped  up.  (Compile  the  program  and  try  it.) 

The  main  menu  works  as  described  above.  However,  one  of  the  panes — the  one  that  brings 
up  the  submenu — has  an  arrow  pointing  to  the  right  after  its  label.  This  pane  does  not  high 
light  itself  when  the  pointer  moves  inside  (telling  the  user  that  this  pane  is  different). 
Instead,  when  the  user  moves  the  pointer  out  through  the  right  edge  of  the  pane,  the  submenu 
pops  up.  The  submenu  operates  just  like  the  main  menu.  When  the  button  is  released  inside 
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Figure  12-5.  xmenuS:  cascaded  spring-loaded  menus 

either  menu,  the  callback  function  associated  with  the  chosen  pane  will  be  invoked.  When 
the  button  is  released  outside  of  either  menu,  both  menus  pop  down.  If  the  pointer  is  moved 
back  out  of  the  submenu  into  the  main  menu,  only  the  submenu  pops  down. 

To  create  the  submenu,  we  create  a  new  pop-up  shell,  Box  widget,  and  a  set  of  Command 
widgets,  and  add  callbacks  for  each  function  the  submenu  panes  will  invoke  (in  this  example, 
one  common  callback).  Then  we  write  three  actions;  PlaceMenu  (which  you  have  already 
seen),  CheckRightAndPopupSubmenu  (which  places  and  pops  up  the  submenu  if  the 
pointer  leaves  the  main  menu  pane  through  its  right  side),  and  CheckLef tAndPopdown- 
Submenu  (which  pops  down  the  submenu  if  the  pointer  leaves  the  submenu  through  the  por 
tion  touching  the  main  menu).  These  actions  are  shown  in  Example  12-5. 

Example  12-5.  xmenuS:  actions  that  place,  pop-up,  and  pop-down  main  menus  and  sub 
menus 

void  PlaceMenu (w,  event) 
Widget  w; 

XButtonEvent  *event; 
{ 

Arg  args [5] ; 

int  i; 

/*  should  make  sure  coordinates  let  menu  fit  on  screen  */ 
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Example  12-5.   xmenuS:  actions  that  place,  pop-up,  and  pop-down  main  menus  and  sub 
menus  (continued) 

/*   move    submenu    shell    to    slightly    left    and   above   button 
*    press   position    */ 

i    =    0; 

XtSetArg(args[i]  ,  XtNx,  event->x_root  -  10); 
XtSetArg(args[i]  ,  XtNy,  event->y_root  -  10); 
XtSetValues  (pshell,  args,  i)  ; 

} 

void  CheckRightAndPopupSubmenu  (w,  event) 
Widget  w; 

XLeaveWindowEvent  *event; 
{ 

Arg  arg; 

int  i; 

Dimension  height; 

i  =  0; 

XtSetArg(arg,  XtNheight,  Sheight)  ;   i++; 

XtGetValues  (w,  &arg,  i)  ; 

if  (  (event->x  >  0)  &&  (event->y  >  0)  &&  (event->y  <  height))  { 
/*  move  submenu  shell  to  start  just  right  of  pane, 

*  using  an  arbitrary  offset  to  place  pointer  in 

*  first  item.  */ 
i  =  0; 

XtSetArg(args  [i]  ,  XtNx,  event->x_root)  ;   i++; 
XtSetArg(args  [i]  ,  XtNy,  event->y_root  -  12); 
XtSetValues  (subshell,  args,  i)  ; 
XtPopup  (subshell,  XtGrabNonexclusive)  ; 


void  CheckLeftAndPopdownSubmenu  (w,  event,  params) 

Widget  w; 

XLeaveWindowEvent  *event; 

String  params; 

{ 

Arg  arg; 

Dimension  sub_height,  menu_height; 

Position  dummy_menu_x,  menu_y; 

int  i; 

i  =  0; 

XtSetArg(arg,  XtNheight,  &sub_height)  ; 

XtGetValues  (subbox,  &arg,  i)  ; 

i  =  0; 

XtSetArg(arg,    XtNheight,    &menu_height)  ; 

XtGetValues  (menubox,    &arg,    i)  ; 

XtTranslateCoords  (menubox,  /*   Widget    */ 

(Position)    0,  /*    x   */ 

(Position)    0,  /*    y   */ 

&dummy_menu_x,    &menu_y)  ;  /*    coords   on    root    window    */ 

if    (  (event->x   <    0)    &&     (event->y   >=    0)    && 
(event->y   <=    sub_height)    && 
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Example  12-5.   xmenuS:  actions  that  place,  pop-up,  and  pop-down  main  menus  and  sub 
menus  (continued) 

(event->y_root    <=   menu_y   +   menu_height)  )     { 
/*   moved   out    left    side    (requires   that    it 

*   move    out    directly   into   the   main   menu)     */ 
XtPopdown  (subshell)  ; 


As  usual,  the  application-defaults  file  specifies  which  events  trigger  these  actions.  We'll 
show  this  file  in  a  moment,  but  for  now  you  need  to  know  just  that  CheckRightAnd- 
PopupSubmenu  and  CheckLeftAndPopdownSubmenu  are  triggered  by  Leave- 
Notify  events.  We  want  the  submenu  to  pop  up  and  down  only  when  the  pointer  leaves 
through  certain  parts  of  certain  sides  of  the  widget  —  the  entire  right  side  of  a  pane  for  pop 
ping  it  up,  and  the  part  of  the  submenu  touching  the  main  menu  on  the  left  side  for  popping  it 
down.  These  two  actions  are  called  in  response  to  all  LeaveNotify  events,  and  they 
check  if  the  pointer  left  through  the  correct  parts  before  popping  up  and  down  the  submenu. 

As  you  may  recall,  we  mentioned  earlier  that  no  matter  what  the  arguments,  xt  Popup  and 
all  other  Xt  facilities  for  grabbing,  except  MenuPopup,  make  no  passive  grab,  and  therefore 
can't  be  used  for  spring-loaded  or  drop-down  main  menus.  It  turns  out  that  for  submenus  the 
opposite  is  true  —  XtPopup  and  xtCallback*  work  fine,  and  but  MenuPopup  is  inap 
propriate,  because  no  new  passive  grab  is  needed.  The  original  grab  directs  events  normally 
to  all  widgets  in  the  application  including  the  submenu,  and  directs  all  events  that  occur  out 
side  the  application  to  pshell. 

The  CheckRightAndPopupSubmenu  action  calls  XtPopup  with  a  grab  mode  of  Xt- 
GrabNonexclusive.  This  grab  mode  controls  Xt's  event  dispatching  within  the  applica 
tion  —  it  has  nothing  to  do  with  the  passive  grab  that  Xt  makes  from  the  MenuPopup  action. 
XtGrabNonexclusive  means  that  widgets  in  the  cascade  but  outside  of  the  submenu 
will  continue  to  get  events  normally.  The  grab  mode  specified  in  the  call  to  XtPopup,  or 
specified  by  the  standard  pop-up  callback  function  selected  (xtCallbackExclusive  or 
xtCallbackNonexclusive)  merely  control  the  event  dispatching  within  the  applica 
tion. 

As  an  exercise,  you  may  want  to  modify  the  example  so  that  CheckRightAndPopup 
Submenu  calls  XtPopup  with  a  grab  mode  of  XtGrabNonexclusive.  The  xtGrab- 
Exclusive  mode  means  that  only  the  most  recent  pop  up  popped  up  will  get  events,  while 
XtGrabNonexclusive  means  that  all  pop  ups  in  a  popped  up  cascade  will  get  events.  In 
this  case,  when  the  submenu  is  popped  up,  it  alone  will  get  pointer  events  if  you  use  grab 
mode  XtGrabExclusive,  while  both  it  and  the  main  menu  will  get  pointer  events  if  you 
use  grab  mode  XtGrabNonexclusive.  Because  of  the  logic  that  pops  down  the  sub 
menu  when  the  pointer  leaves  it  through  the  portion  adjoining  the  main  menu,  you  can  see 
this  difference  only  if  you  move  out  through  another  part  of  the  submenu  and  then  around 
into  the  main  menu  again.  (In  the  example  code  distribution,  xmenuS.c  uses  XtGrab 
Nonexclusive  and  xmenu4.c  uses  XtGrabExclusive,  so  that  you  can  compare  the 
results  of  these  two  flags.) 
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The  user-interface  conventions  for  a  particular  widget  set  usually  specify  which  kinds  of  pop 
ups  should  have  exclusive  grabs  and  which  nonexclusive.  Note  that  the  effect  of  these  two 
grab  modes  is  the  same  unless  there  is  more  than  one  pop-up  widget  in  a  cascade  visible. 

CheckRightAndPopupSubmenu  places  the  submenu  itself  (instead  of  using  a  separate 
action)  because  the  menu  should  be  placed  only  when  it  is  first  popped  up.  If  the  placement 
code  were  a  separate  action,  it  would  be  called  every  time  a  Leavewindow  event  arrived, 
even  if  not  through  the  correct  border  of  the  widget  (Remember  that  this  code  is  in  an  action 
rather  than  a  callback  because  it  uses  the  contents  of  the  event.) 

The  translation  portion  of  the  application-defaults  file  forxmenuS  is  shown  in  Example  12-6. 
Example  12-6.  XMenuS:  translation  portion  of  application-defaults  file 

!    Appearance    resources 
*menupane3 . label :       Colors   Menu    — > 
(other  appearance  resources  not  shown) 

i 

!  Translation  resources 
i 

!   popping  up  Main  Menu 
*  label . translations : \ 

<BtnDown>:     placeMenuO  MenuPopup (pshell) 

i 

!  Main  Menu  translations 
*menubox . Command . translations : \ 

<EnterWindow>:      highlight ()  \n\ 

<LeaveWindow> :      reset ()  \n\ 

<BtnUp>:  set()  notify ()  unset () 

t 

!  SubMenu  translations 
*subbox . Command . translations : \ 

<EnterWindow>:      highlight ()  \n\ 

<LeaveWindow> :      reset ()  \n\ 

<BtnUp>:  set()  notify ()  unset () 

i 

!   popping  down  both  menus 
*pshell . translations : \ 

<BtnUp>:  MenuPopdown (subshell)  MenuPopdown (pshell) 

i 

!   popping  up  submenu  (maybe) 
*menubox .menupane3 . translations : \ 

<LeaveWindow> :     CheckRightAndPopupSubmenu ( ) 

i 

!   popping  down  submenu  (maybe) 
*subbox . translations : \ 

<LeaveWindow> :     checkLeftAndPopdownSubmenu (subbox) 

The  first  three  translation  tables  handle  popping  up  the  main  menu  and  making  the  menu 
Command  widgets  work  as  expected.  We've  seen  these  in  previous  examples. 
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The  translation  table  for  pshell  pops  down  one  or  both  menus;  no  error  or  warning  is 
caused  if  only  the  main  menu  is  up.  This  translation  table  works  because  the  button  release  is 
sent  to  pshell  if  it  occurs  outside  a  menu  regardless  of  whether  just  the  main  menu  or  both 
menus  are  up. 

In  this  case,  menu  pane  3  is  the  pane  that  will  pop  up  the  submenu.  The  label  for  this  pane  is 
shown  at  the  top  of  Example  12-6.  The  translation  for  this  pane  replaces  all  the  normal  trans 
lations  for  highlighting  and  notifying  with  a  single  translation  for  LeaveWindow  events. 
These  events  in  this  widget  trigger  the  CheckRightAndPopupSubmenu  action  which 
has  already  been  described. 

The  translations  for  the  subbox  widget  invoke  CheckLeftAndPopdownSubmenu 
action  to  check  whether  the  pointer  left  the  submenu  through  its  left  side  (i.e.,  if  it  went  back 
into  the  previous  pop-up  menu  in  the  cascade).  In  this  case,  the  submenu  is  popped  down, 
but  the  original  pop  up  remains  visible. 

The  pane  that  will  pop  up  the  submenu  and  its  event  handling  characteristics  is  controlled 
from  the  application-defaults  file.  Therefore,  it  may  seem  like  you  can  change  which  menu 
pane  invokes  the  submenu  simply  by  changing  the  application-defaults  file.  This  is  true  here, 
because  the  menu  actions  are  nonfunctional,  and  simply  call  a  common  callback.  But  it 
would  not  be  possible  if  each  pane  invoked  its  own  callback.  To  give  the  user  the  freedom  to 
rearrange  the  menu,  you  would  have  to  use  actions  instead  of  callbacks. 

Note  that  you  can  define  accelerators  for  any  of  the  menus  shown  up  to  this  point  simply  by 
placing  settings  for  the  XtNaccelerators  resource  in  the  application-defaults  file.  You  would 
set  this  resource  for  every  Command  widgets  in  the  menus.  This  provide  keyboard  shortcuts 
for  popping  up  the  menu  and  choosing  a  pane.  However,  remember  to  make  sure  that  each 
key  combination  is  unique. 

12.2.4    Using  the  R4  SimpleMenu  Widget 

Once  you  have  R4,  you  can  use  a  real  menu  widget;  the  R4  SimpleMenu  widget.  This  inter 
nals  of  this  widget  and  its  children,  which  are  gadgets,  will  be  described  later.  This  section 
describes  a  simple  application  that  uses  the  SimpleMenu  widget* 

R4  supplies  three  types  of  panes  to  be  used  with  the  SimpleMenu  widget  SmeBSB  (and 
entry  composed  of  a  bitmap,  a  string,  and  another  bitmap),  SmeLine  (a  horizontal  line 
between  entries),  and  Sme  (a  blank  entry).  The  SimpleMenu  widget  is  itself  a  subclass  of  the 
pop-up  shell  widget,  and  therefore  no  separate  pop-up  shell  needs  to  be  created. 

R4  also  provides  a  MenuButton  widget,  which  is  a  subclass  of  Command  with  built-in  place 
ment  and  pop-up  code.  Using  a  MenuButton  to  invoke  a  menu  makes  it  even  simpler  to 
implement  a  drop-down  menu,  since  the  pop  up  and  placement  code  can  be  eliminated  from 
the  application. 


*Note  that  if  you  have  an  R3  version  of  the  Xt  Intrinsics  library,  you  cannot  use  the  SimpleMenu  widget  even  if  you 
can  get  its  code.  The  widget  depends  on  changes  to  Xt  introduced  in  R4. 
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The  xmenu?  application  shown  in  Example  12-7  creates  a  SimpleMenu  widget  with  panes  of 
all  three  types.  The  menu  is  invoked  in  drop-down  style  using  the  R4  MenuButton  widget* 

As  an  additional  enhancement,  the  menu  marks  or  unmarks  each  item  when  it  is  selected  in 
addition  to  calling  a  callback  function.  This  iteration  marks  entries  with  the  X  logo,  which  is 
available  as  a  standard  bitmap  in  lusrlincludelXll /bitmaps  (on  UNIX  systems). 

Figure  12-6  shows  the  appearance  of  the  program. 
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Figure  12-6.  xmenu?:  a  menu  using  the  Athena  SimpleMenu  widget 


Example  12-7.  xmenu?:  using  the  SimpleMenu  widget  and  its  children 

tinclude  <stdio.h> 

tinclude  <Xll/Intrinsic .h> 
tinclude  <Xll/StringDef s .h> 
tinclude  <Xll/bitmaps/xlogol6> 

/*  works  under  R4  and  later  only  */ 
tinclude  <Xll/Xaw/MenuButton.h> 
tinclude  <Xll/Xaw/SimpleMenu .h> 
tinclude  <Xll/Xaw/SmeBSB.h> 
tinclude  <Xll/Xaw/SmeLine .h> 

tdefine  NUM_MENU_ITEMS  12 

static  String  menu_entry_names [ ]  =  { 
"quit", 
"iteml", 
"item2", 
"item3", 
"line", 
" itemS ", 
"itemG" 


*This  example  was  written  by  Chris  Peterson  of  MIT  Project  Athena,  and  modified  only  slightly  by  the  authors. 
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Example  12-7.  xmenu?:  using  the  SimpleMenu  widget  and  its  children  (continued) 

"itemV", 
"blank", 
"menul", 
"menu2", 
"menu3", 
}; 

static  Boolean  status  [NUM_MENU_ITEMS]  ; 
static  Pixmap  mark; 

/*  ARGSUSED  */ 

static  void 

MenuSelect  (w,  pane_num,  garbage) 

Widget  w; 

int  pane_num;  /*  client_data  */ 

caddr_t  garbage;  /*  call_data  */ 

{ 

Arg  arglist  [1]; 

Cardinal  num_args  =0; 

print  f(  "Menu  item  %s  has  been  selected.  \n",  XtName  (w)  )  ; 

if  (pane_num  ==  0)  /*  quit  selected.  */ 

exit  (0)  ; 

if  (status  [pane_num]  ) 

XtSetArg(arglist  [num_args]  ,  XtNleftBitmap,  None); 
else 

XtSetArg  (arglist  [num_args]  ,  XtNleftBitmap,  mark)  ; 
num_args++; 
XtSetValues  (w,  arglist,  num_args)  ; 

status  [pane_num]  =  !  status  [pane_num]  ; 

} 

void 

main(argc,  argv) 

char  **  argv; 

int  argc; 

{ 

Widget  topLevel,  menu,  button,  entry; 

int  i; 

Arg  arglist  [1]  ; 

topLevel  =  Xtlnitialize  (argv  [0]  ,  "XMenu7",   NULL,  0, 
(unsigned  int*)  &argc,  argv); 

button  =  XtCreateManagedWidget  ("menuButton", 

menuButtonWidgetClass,  topLevel, 

arglist,  (Cardinal)  0)  ; 
menu  =  XtCreatePopupShell  ("menu",  simpleMenuWidgetClass, 

button,  NULL,  0)  ; 


for  (i  =  0;  i  <  NUM_MENU_ITEMS  ; 

String  item  =  menu_entry_names  [i]  ; 

if  (i  ==  4)       /*  use  a  line  pane  */ 
entry  =  XtCreateManagedWidget  (item, 

lineMenuEntryObjectClass,  menu, 
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Example  12-7.  xmenu7:  using  the  SimpleMenu  widget  and  its  children  (continued) 

NULL,  0); 
else  if  (i  ==  8)  /*  blank  entry  */ 

entry  =  XtCreateManagedWidget (item, 

menuEntryObjectClass,  menu,  NULL,  0) ; 
else  { 

entry  =  XtCreateManagedWidget (item, 

bSBMenuEntryObjectClass,  menu,  NULL,  0)  ; 

XtAddCallback (entry,  XtNcallback,  MenuSelect, 
(caddr_t)  i) ; 

} 

} 

mark  =  XCreateBitmapFromData (XtDisplay (topLevel) , 

RootWindowOf Screen (XtScreen (topLevel) ) , 
xlogo!6_bits,  xlogo!6_width,  xlogo!6_height) ; 

XtRealizeWidget (topLevel) ; 
XtMainLoop ( ) ; 

} 

You  will  notice  that  each  pane  has  a  xtNle  ft  Bitmap  resource,  which  is  alternately  set  to 
the  X  logo  or  to  nothing  each  time  that  item  is  selected. 

The  application-defaults  file  for  xmenu?  is  shown  in  Example  12-8. 

Example  12-8.  XMenu7:  application-defaults  file 
t 

!  For  Color  workstations  only, 
t 

! Xmenu2*SimpleMenu*f oreground:  SteelBlue 

! Xmenu2*SimpleMenu*menuLabel . foreground:      Gold 
! Xmenu2*SimpleMenu*line . foreground:  Grey 

Xmenu2*menuButton. label :       Click  here  for  menu 

Xmenu2*SimpleMenu*menuLabel .vert Space:        100 

Xmenu2*SimpleMenu*menuLabel . leftMargin:       70 

Xmenu2*SimpleMenu. label :  Main  Menu 

Xmenu2*SimpleMenu*quit*label :  Quit  this  stupid  demo. 

Xmenu2*SimpleMenu*RowHeight :        16 

Xmenu2* SimpleMenu* item7* sensitive:       off 

Xmenu2*SimpleMenu*HorizontalMargins:     30 

!  Just  for  fun: 

Xmenu2*menuLabel*font:  -* -courier-medium-r-normal — 34-*-100-100-*-*-iso8859-l 


Xmenu2*iteml*font 
Xmenu2*item2*font 
Xmenu2*item3*font 
Xmenu2*item4*f ont 
Xmenu2*item5*font 
Xmenu2*item6*font 
Xmenu2*item7*font 
Xmenu2* itemS* font 


'-courier-medium-r-normal — ll-*-100-100-*-*-iso8859-l 
'-courier-bold-r-normal — ll-*-l 00-1 00-*-*-iso885 9-1 
'-courier-medium-r-normal — 14-*-100-100-*-*-iso8859-l 
'-courier-bold-r-normal — 14-*-100-100-*-*-iso8859-l 
'-courier-medium-r-normal — 17-*-100-100-*-*-iso8859-l 
'-courier-bold-r-normal — 17-*-100-100-*-*-iso8859-l 
'-courier-medium-r-normal — 20-*-100-100-*-*-iso8859-l 
'-courier-bold-r-normal — 20-*-l 00-1 00-*-*-iso885 9-1 
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This  file  simply  sets  various  cosmetic  features  of  the  menu.  (See  Appendix  D,  Naming  Con 
ventions  for  information  on  font-naming  conventions.)  Naturally,  you  could  easily  set  the 
strings  for  each  menu  entry  in  this  file.  Note  that  there  are  no  translation  tables  in  this  file 
because  MenuButton  and  SimpleMenu  are  doing  exactly  what  they  were  designed  to  do. 

Accelerators  can  be  defined  for  menus  with  gadget  children,  but  not  in  the  usual  sense.  They 
cannot  be  defined  to  invoke  the  actions  of  the  gadget  children,  but  they  can  invoke  global 
application  actions,  which  for  menus  is  usually  good  enough.  For  example,  in  the  R4  xmh, 
one  item  on  one  of  the  menus  incorporates  new  mail.  From  the  widget,  the  notify  action 
of  the  menu  pane  gadget  calls  the  DolncorporateNewMail  callback  function.  The 
xtNaccelerators  resource  for  the  SimpleMenu  widget  itself  (not  the  gadgets)  maps  a 
Meta-I  key  event  into  a  call  to  the  XmhlncorporateNewMail  global  action.  Xmh- 
IncorporateNewMail  then  calls  DolncorporateNewMail.  This  use  of  accelera 
tors  depends  on  having  both  a  callback  and  an  action  form  of  each  function. 


12.3  About  Dialog  Boxes 

Although  we  have  been  talking  so  far  exclusively  about  menus,  much  that  has  been  said  is 
also  true  of  dialog  boxes.  Both  menus  and  dialog  boxes  that  get  user  input  usually  need  to 
get  that  input  before  other  application  functions  can  be  invoked.  Of  course,  one  way  to  dis 
able  all  other  application  functions  is  to  make  them  insensitive  with  xtSetSensitive 
(passing  it  FALSE).  Setting  the  sensitivity  of  one  common  ancestor  does  the  trick,  but  even 
this  is  too  slow  because  all  the  widgets  redraw  themselves  dimmed  or  grayed.  It  is  much  fas 
ter  to  use  a  grab.  Unlike  menus,  which  require  the  grab  in  order  to  get  button  release  events 
outside  the  application  so  they  can  pop  down  properly,  dialog  boxes  do  not,  strictly  speaking, 
need  a  grab.  But  they  usually  make  the  grab  anyway  to  disable  other  application  functions. 

Dialog  boxes  can  also  invoke  other  dialog  boxes.  For  example,  a  dialog  box  that  gets  input 
might  check  the  validity  of  the  input  before  popping  down  the  dialog,  and  if  incorrect,  pop  up 
a  message  telling  the  user  the  problem  with  the  input.  Cascaded  dialog  boxes  are  imple 
mented  the  same  way  as  cascaded  menus.  Note  that,  as  a  general  rule,  sub-dialog  boxes  are 
popped  up  with  grab  mode  xtGrabExclusive,  which  means  that  the  user  must  satisfy 
the  most  deeply  nested  dialog  first. 

Some  pop  ups  do  not  need  to  disable  other  application  functions.  For  example,  imagine  a 
dialog  box  that  informed  the  user  of  some  fact  without  requiring  confirmation.  This  kind  of 
pop  up  would  be  popped  up  with  grab  mode  xtGrabNone,  allowing  the  user  to  continue 
with  other  application  functions. 

We  pointed  out  earlier  that  the  built-in  callback  functions  for  popping  up  a  widget  are  not 
useful  for  menus  because  they  make  no  passive  pointer  grab.  However,  they  come  in  handy 
for  dialog  boxes.  The  functions  xtCallbackNone,  xtCallbackExclusive,  and 
xtCallbackNonexclusive  can  be  used  to  pop-up  dialog  boxes,  as  long  as  the  position 
of  the  dialog  box  need  not  depend  on  information  in  an  event 

We  haven't  shown  how  to  use  Xt's  standard  callback  for  popping  down  a  widget  xt- 
CallbackPopdown.  Instead  of  calling  xtPopdown  in  the  callback  functions  for  each 
menu  entry,  we  can  add  xtCallbackPopdown  to  the  callback  list  after  the  existing 
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callback  function.  XtCallbackPopdown  requires  an  XtPopdownld  structure  to  be 
passed  as  the  client_data  argument  This  structure  must  contain  the  pop-up  shell  and 
the  widget  that  invoked  the  pop  up  (the  MenuButton  or  Command  widget). 

All  three  of  the  standard  pop-up  callbacks  set  the  invoking  widget  to  insensitive  mode  before 
popping  up  the  widget  xtCallbackPopdown  resets  the  invoking  widget  to  sensitive 
mode.  Therefore,  if  you  use  XtCallbackNone,  XtCallbackNonexclusive,  or 
xtCallbackExclusive,  without  also  using  XtCallbackPopdown,  remember  to  set 
the  widget  to  sensitive  mode  yourself.  This  feature  is  useless  but  also  harmless  when  the  pop 
up  is  spring-loaded,  because  the  invoking  widget  is  often  the  main  application  window  and 
that  widget  rarely  responds  to  sensitivity. 

In  certain  rare  cases,  you  may  want  to  use  xtAddGrab  and  xtRemoveGrab  directly  to 
append  a  widget  to  or  remove  a  widget  from  the  current  pop-up  cascade.  These  functions  are 
called  internally  by  the  Xt  facilities  that  pop  widgets  up  and  down,  and  should  not  be  neces 
sary  on  their  own.  Note  that  these  functions  never  make  a  request  to  the  server  to  start  or 
release  a  passive  pointer  grab — they  affect  only  Xt's  internal  event  dispatching. 


12.4  Gadgets 


When  an  application  includes  many  different  menus  with  many  fields  each,  the  overhead  of 
having  separate  widgets  for  every  menu  pane  becomes  significant.  Because  each  widget 
requires  structures  on  the  client  side  and  windows  on  the  server  side,  every  widget  increases 
the  executable  size  and  server  memory  usage.  It  is  always  a  good  idea  to  minimize  the  num 
ber  of  widgets  used  in  your  application. 

Writing  a  single  widget  that  implements  an  entire  menu,  including  all  its  panes,  solves  this 
problem.  The  widget  could  define  subresources  for  configuring  each  pane.  (The  callback  list 
would  be  one  of  these  subresources.  XtCallCallbacks  could  not  be  used  to  invoke 
these  callbacks  because  it  cannot  distinguish  between  subparts.  However,  the  callbacks  can 
be  called  directly  by  looping  through  the  callback  list.  This  is  awkward,  but  not  too  diffi 
cult)  This  widget  would  not  lack  flexibility  if  the  subparts  are  implemented  as  completely 
separate  code  so  that  the  types  of  menu  panes  are  extensible.  However,  gadgets  turn  out  to  be 
a  more  elegant  solution  to  the  problem. 

As  of  Release  4,  Xt  provides  gadgets,  which  are  simplified  widgets  that  do  not  create  win 
dows.41  Gadgets  require  less  memory  than  widgets  on  the  client  side  (and  less  disk  space  for 
the  executable  file)  and  consume  none  at  all  on  the  server  side.  Gadgets  can  be  used  for  the 
panes  of  a  menu,  solving  all  of  the  problems  just  discussed.  A  gadget  is  fully  configurable 
using  the  resource  database  just  like  a  widget  and  can  have  its  own  callback  list. 

However,  the  reduced  consumption  of  gadgets  does  have  a  price.  Gadgets  have  to  draw  on 
their  parent's  window,  and  they  share  this  space  with  the  parent  and  with  all  other  gadget 
children.  The  gadgets  and  the  parent  must  agree  to  draw  in  certain  areas  only.  For  this 


'"Some  versions  of  the  R3  Intrinsics  have  been  modified  to  support  gadgets.  One  of  these  is  the  version  supplied  by 
OSF  with  early  releases  of  the  Motif  widget  set  However,  the  Intrinsics  as  released  by  the  X  Consortium  in  R3  do 
not  support  gadgets. 
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reason,  gadgets  must  be  used  with  a  special  composite  widget  parent  that  is  prepared  to  man 
age  them  properly. 

The  Release  4  SimpleMenu  widget  is  such  a  parent  It  is  a  composite  widget  designed  to 
manage  gadget  children.  The  gadgets  provided  by  Release  4  are  Sme,  SmeBSB,  and  Sme- 
Line  (where  Sme  stands  for  Simple  Menu  Entry).  These  provide  a  blank  entry  (and  generic 
menu  entry  superclass),  an  entry  which  can  contain  a  bitmap,  a  string,  and  another  bitmap 
(thus  BSB),  and  an  entry  that  draws  a  horizontal  line.  We  will  use  and  describe  this  widget 
and  these  gadgets  both  to  show  how  menu  widgets  are  built  and  to  demonstrate  how  the  par 
ent  and  the  gadgets  work  together. 

Gadgets  do  not  handle  events  automatically  like  widgets,  and  because  they  have  no  windows, 
the  server  does  not  handle  overlapping  between  them.  This  places  certain  demands  on  the 
parent  All  the  gadgets  that  are  children  of  a  particular  parent  share  that  parent's  window. 
The  parent  is  responsible  for  coordinating  the  gadget  children,  telling  them  about  events  by 
calling  their  functions.  Therefore,  the  composite  widget  that  manages  a  group  of  gadgets 
must  be  specially  designed  for  that  purpose,  not  a  general-purpose  composite  or  constraint 
widget  such  as  Box  or  Form.  It  is  possible  for  a  composite  widget  to  manage  both  gadget  and 
widget  children,  but  its  code  has  to  be  more  involved  to  do  this. 

Like  normal  widgets,  gadgets  provide  their  own  code  to  redraw  themselves  in  their  expose 
method.  However,  since  gadgets  do  not  receive  events,  they  depend  on  the  parent  to  directly 
call  their  expose  method.  The  parent  keeps  track  of  the  geometry  of  each  child,  and  when 
the  parent's  expose  method  is  called,  this  method  calculates  whether  the  area  exposed 
overlaps  any  of  the  gadget  children.  If  the  area  exposed  does  overlap  a  gadget,  the  parent's 
expose  method  calls  that  gadget's  expose  method,  which  redraws  the  area. 

A  gadget's  actions  also  have  to  work  differently  from  widget  actions  because  of  the  fact  that 
gadgets  don't  get  events.  A  gadget  defines  its  actions  as  methods — as  fields  in  its  class  part 
structure — instead  of  in  an  action  list  and  translation  table.  It  initializes  these  fields  directly 
to  pointers  to  functions  during  class  initialization.  The  parent  widget  has  corresponding 
actions  that  are  defined  and  operate  like  normal  actions,  except  that  they  determine  which 
gadget  the  event  that  invoked  the  action  occurred  in  and  call  the  gadget  method  correspond 
ing  to  that  action.  In  other  words,  the  parent  has  actions  that  operate  the  gadget  children. 

One  weakness  of  a  menu  composed  of  gadget  panes  is  that  gadgets  cannot  have  an  accelera 
tor  table.  Therefore,  accelerators  cannot  be  used  to  provide  a  keyboard  equivalent  that  would 
invoke  each  menu  pane. 

The  parent  of  gadgets  has  to  position  the  gadget  children  so  that  they  do  not  overlap,  or  take 
care  of  the  consequences  if  they  do  overlap.  Since  the  gadgets  draw  on  the  parent's  window, 
if  they  did  overlap  they  would  draw  over  each  other's  graphics,  with  unpredictable  results. 
The  parent  would  have  to  calculate  the  area  of  overlap  between  two  gadgets,  and  clear  this 
area  before  letting  one  of  the  gadgets  draw  itself.  (A  gadget  could  clear  its  own  area  before 
drawing,  but  this  would  be  unnecessary  in  many  cases,  and  would  cause  flashing.) 
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Gadgets  are  subclasses  of  RectObj,  one  of  the  invisible  superclasses  of  Core  that  we  have  so 
far  ignored  because  for  widgets  it  is  safe  to  assume  that  Core  is  the  top  of  the  widget  class 
hierarchy.*  The  actual  class  hierarchy  leading  up  to  Core  is  shown  in  Figure  12-7. 


Object 


RectObj 


Windo  wObj 


Core 


defines  callback  handling 


defines  geometry  resources 
and  sensitivity 


defines  window  attribute 
resources 


packages  superclasses  for 
inheritance  by  widgets 


Figure  12-7.  Class  hierarchy  derivation  of  Core 

The  superclasses  of  Core  are  not  real  classes  in  the  sense  that  they  do  not  play  by  all  the  rules 
we  have  described  in  Chapter  5,  Inside  a  Widget.  For  one  thing,  each  shares  what  we  have 
been  calling  the  Core  class  structure  instead  of  adding  its  own  part  structure.  Applications 
are  never  intended  to  create  instances  of  these  superclasses — they  are  really  just  part  of  the 
implementation  of  Xt.  Instead  of  developing  all  the  characteristics  of  widgets  in  one  large 
base  class  Core,  it  made  more  sense  to  implement  Xt  in  object-oriented  fashion  by  dividing 
the  implementation  into  separate  pseudo-classes.  It  is  important  to  know  what  each  early 
class  defines  simply  so  that  you  know  what  characteristics  are  available  in  gadgets  and  which 
are  available  only  in  widgets.  Each  class  defines  the  following  features: 

•  Object  defines  only  the  xtNdes  troy  Callback  resource,  and  the  underlying  support 
for  callbacks  in  general. 

•  RectObj  defines  the  geometry  resources  (xtNx,  XtNy,  XtNwidth,  xtNheight,  and 
XtNborder_width)        and        the        resources        that       control        sensitivity: 


*In  R3,  the  header  files  for  these  invisible  classes  are  not  so  invisible.  They  were  all  present  in  lusrlinclude/Xll  with 
all  the  other  Xt  header  files.  In  R4,  only  the  header  files  for  RectObj  are  public,  so  that  you  can  write  and  compile 
gadgets. 
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XtNancest  or  Sensitive  and  xtNsensitive.  RectObj  itself  doesn't  use  the 
sensitivity  resources.  They  are  provided  at  this  level  in  the  hierarchy  so  that  sensitivity 
can  be  set  for  gadgets.  Gadgets  draw  themselves  according  to  these  resources  (gray  if 
insensitive),  and  check  these  resources  in  their  action  routines  (stored  in  their  class  part 
methods),  invoking  their  callback  function  only  if  sensitive. 

•  WindowObj  adds  many  window-oriented  resources:  ones  that  control  window  attributes 
such  as  the  background  pixmap,  permanent  window  features  such  as  the  window  depth, 
and  event  resources  such  as  translations  and  accelerators.   It  also  includes  the  xt- 
NmappedWhenManaged  resource.  The  WindowObj  class  is  known  as  the  "unnamed 
class"  because  it  never  appears  in  widget,  gadget,  or  application  code.  Widgets  are  sub 
classed  from  Core,  while  gadgets  are  subclassed  from  RectObj.  The  exact  features  of 
WindowObj  are  subject  to  change  and  should  not  be  relied  upon.  For  example,  a  system 
vendor  is  allowed  to  move  some  of  the  characteristics  of  WindowObj  into  Core. 

The  Core  class  structure  actually  is  inherited  all  the  way  from  RectObj.  Therefore,  the  class 
structure  in  gadgets  is  the  Core  class  structure  you  are  already  familiar  with.  All  the  event- 
related  fields  in  the  Core  class  part  structure  of  gadgets  are  unused.  The  only  exception  is  the 
expose  method,  which  is  present,  but  draws  on  the  parent's  window  and  is  not  called  in  the 
usual  way  by  Xt  because  the  gadget  receives  no  events.  The  remaining  non-event-related 
fields  have  the  same  purpose  as  for  widgets,  including  all  the  remaining  methods. 

Without  further  ado,  let's  take  a  look  at  a  gadget,  and  then  at  a  gadget  parent. 

12.4.1    Inside  a  Gadget 

Many  portions  of  a  gadget's  code  are  exactly  the  same  as  those  of  a  widget,  as  described  in 
Chapter  5,  Inside  a  Widget.  This  section  briefly  summarizes  the  parts  that  are  identical  so 
that  you  know  that  nothing  is  left  out,  and  describe  the  differences  in  detail. 

The  code  for  gadgets  and  widgets  includes  the  same  three  implementation  files  with  the  same 
naming  conventions.  As  in  Chapter  5,  we'll  take  the  three  implementation  files  one  at  a  time, 
beginning  with  the  private  header  file,  then  the  code  file,  and  then  the  public  header  file. 

As  in  widget  code,  many  of  the  conventions  described  here  are  automatically  taken  care  of 
for  you  when  you  are  writing  a  new  gadget  if  you  copy  all  three  files  of  an  existing  gadget 
and  then  globally  change  the  gadget  class  name. 

The  Athena  menu  pane  gadgets  are  implemented  in  two  class  levels: 

•  Sme  (Simple  Menu  Entry)  defines  the  callback  for  an  entry,  the  actions  to  highlight, 
unhighlight,  and  notify,  and  the  code  that  allows  subclasses  to  inherit  or  replace  these 
actions  (because  they  are  defined  as  methods).  The  actual  functions  for  highlight  and 
unhighlight  are  empty,  while  the  notify  action  calls  the  callback.  The  expose  method 
of  this  gadget  is  also  empty.  This  gadget  can  be  used  by  itself  to  create  a  blank  entry. 

•  SmeBSB  and  SmeLine  are  each  subclasses  of  Sme.  SmeLine  replaces  only  the  expose 
method  of  its  superclass.  SmeBSB  replaces  both  the  expose  method  and  the  highlight 
and  unhighlight  actions  of  the  superclass.  (Sme  can  be  subclassed  to  create  new  types  of 
menu  entries.) 
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The  following  sections  describe  both  Sme  and  SmeBSB. 


12.4.2    Private  Header  File 

The  private  header  file  for  a  gadget  is  identical  in  format  to  the  private  header  file  for  a 
widget  It  defines  a  class  part  structure  for  this  class  of  gadget,  and  then  a  complete  class 
structure  including  the  class  parts  of  superclasses  and  this  class.  The  only  difference  is  that  a 
gadget  inherits  its  features  from  Object  and  RectObj  while  a  widget  inherits  from  Core. 
Example  12-9  shows  the  complete  class  structure  of  the  R4  Athena  Sme  gadget. 

Example  12-9.  Sme  gadget:  class  part  and  complete  class  structure  declaration 

typedef  struct  _SmeClassPart  { 

void  ("highlight) () ; 

void  (*unhighlight) ( ) ; 

void  (*notify) () ; 

XtPointer  extension; 
}  SmeClassPart; 

/*  Full  class  record  declaration  */ 
typedef  struct  _SmeClassRec  { 

RectOb jClassPart     rect_class; 

SmeClassPart  menu_entry_class; 
}  SmeClassRec; 

tdefine  XtlnheritHighlight    ( (_XawEntryVoidFunc)  _XtInherit) 
fdefine  XtlnheritUnhighlight  XtlnheritHighlight 
I!   tdefine  XtlnheritNotify       XtlnheritHighlight 

Notice  that  the  complete  class  structure  declaration  does  not  include  the  class  part  for  the 
Object  class,  even  though  it  is  a  superclass.  This  is  because  all  the  superclasses  of  Core  share 
the  same  class  part  structure. 

The  class  part  structure  for  Sme  defines  three  methods — these  are  essentially  the  gadget's 
actions,  but  they  will  be  invoked  by  the  gadget  parent's  actions,  not  directly  by  Xt.  The 
extension  field  allows  fields  to  be  added  to  this  structure  in  a  future  version  while  retain 
ing  binary  compatibility.  In  a  future  version  this  field  could  be  changed  to  point  to  an  exten 
sion  structure.* 

Any  class  that  defines  methods  must  provide  code  to  allow  them  to  be  inherited  or  replaced 
by  subclasses.  The  Sme  class  therefore  must  define  the  Xt  Inherit  constants  that  allow 
the  methods  to  be  inherited.  The  .c  code  file  provides  the  class_part_init  method  that 
allows  them  to  be  replaced.  (See  Section  11.4.5.) 

In  the  private  header  file  for  SmeBSB,  the  class  part  structure  would  contain  only  the  exten 
sion  field,  because  SmeBSB  will  be  using  the  highlight,  unhighlight,  and  notify  fields  defined 
by  Sme.  However,  the  .c  file  will  initialize  these  fields  to  point  to  its  own  functions. 


*Note  that  the  extension  field  is  defined  as  type  XtPointer.  In  R4,  all  occurrences  of  caddr_t  have  been 
replaced  with  XtPointer.  On  most  systems,  XtPointer  will  be  defined  to  be  caddr_t.  But  for  some  archi 
tectures,  caddr_t  is  too  small  to  hold  a  pointer  to  a  function.  On  such  systems,  XtPointer  will  be  defined  to  be 
larger.  The  caddr_t  type  will  continue  to  work  on  most  systems,  but  you  are  advised  to  use  XtPointer  instead 
for  maximum  portability. 


376  X  Toolkit  Intrinsics  Programming  Manual 


The  instance  part  structure  and  complete  instance  structure  of  Sme  are  shown  in  Example 
12-10. 

Example  12-10.  Sme  gadget:  instance  part  and  complete  instance  structure  declaration 

typedef  struct  { 

/*  resources  */ 

XtCallbackList  callbacks;    /*  The  callback  list  */ 
}  SmePart; 

typedef  struct  _SmeRec  { 

ObjectPart      object; 

RectObjPart     rectangle; 

SmePart   menu_entry; 
}  SmeRec; 

The  SmePart  adds  a  callbacks  resource.  The  complete  SmeRec  includes  the  prior  ele 
ments  in  the  widget  hierarchy:  ObjectPart  and  RectObjPart.  Note  that  unlike  the 
class  structure,  the  Object  class  does  appear  in  the  complete  instance  structure,  because  the 
superclasses  of  Core  do  not  share  instance  structures. 

The  instance  part  structure  for  SmeBSB  includes  the  usual  fields  to  maintain  the  graphics 
state  of  the  entry,  including  the  label,  colors,  font,  GCs,  and  positioning  information.  The 
complete  instance  structure  for  SmeBSB  is  the  same  as  the  one  for  Sme  but  with  the  Sme- 
BSBPart  structure  added  at  the  end. 


12.4.3   The  Gadget  Source  File 

The  source  file  for  a  gadget  is  identical  in  form  to  a  widget  source  file.  The  only  differences 
are  that  the  superclass  of  a  gadget  in  the  class  structure  initialization  is  rectObjClass- 
Rec,  and  the  complete  instance  structure  type  is  called  SmeOb  ject  for  a  gadget  where  it 
would  have  been  SmeWidget  if  the  entry  was  a  true  widget.  Therefore,  SmeOb  ject  is 
the  type  into  which  you  cast  the  pointer  to  the  instance  structure  before  accessing  the  struc 
ture's  fields  in  all  the  widget  methods. 

In  addition,  several  of  the  Core  class  structure  fields  that  might  be  used  in  a  widget  are  never 
used  in  gadgets.  The  following  is  the  complete  list  of  fields  that  are  always  initialized  to  a 
certain  value  in  a  gadget: 

•  realize  set  to  NULL 

•  actions  set  to  NULL 

•  num_a  c  t  i  o  n  s  set  to  0  (zero) 

•  compress_motion  set  to  FALSE 

•  compress_exposure  set  to  FALSE 

•  compress_enterleave  set  to  FALSE 

•  visible    interest  set  to  FALSE 
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•  resize  set  to  NULL 

•  display_accelerators  set  to  NULL 

Setting  these  fields  otherwise  (of  the  right  type)  probably  won't  cause  the  gadget  to  crash,  but 
won't  accomplish  anything  useful  either. 

Gadgets,  like  widgets,  should  always  define  the  query_geometry  method,  and  either 
define  set_values_almost  or  initialize  it  to  xtlnheritSetValuesAlmost.  The 
remainder  of  the  fields  and  methods  have  the  same  purpose  and  are  used  in  the  same  way  as 
for  widgets. 

There  are,  however,  slight  differences  in  the  code  for  certain  gadget  methods.  The  expose 
method  checks  not  only  its  own  sensitivity  but  also  its  parent's  sensitivity  before  deciding 
whether  to  draw  the  entry  in  normal  colors  or  grayed.  When  creating  GCs  using  XGreate- 
GC  or  creating  any  other  server  resources  from  the  initialize  method  using  an  Xlib  call, 
you  must  remember  to  use  the  parent's  window,  since  the  gadget  has  no  window,  (xt- 
window  is  not  smart  enough  to  give  you  the  parent's  window  ID  in  the  case  of  gadgets.) 
Also,  the  parent's  resource  values,  such  as  background_pixel,  may  be  used  to  provide 
data  in  common  among  all  instances  of  a  subclass  like  SmcBSB. 


12.4.4  The  Public  Header  File 

The  only  difference  in  the  public  header  file  between  widgets  and  gadgets  is  that  what  would 
have  been  widget  for  a  widget  is  Object  for  a  gadget.  As  mentioned  previously,  if  you 
are  writing  a  gadget  you  should  start  by  copying  the  files  for  an  existing  gadget  and  then 
globally  change  names.  Then  you  will  start  with  the  proper  conventions  already  in  place. 

12.4.5  The  Gadget  Parent 

A  gadget  parent  is  a  composite  widget  designed  to  manage  gadget  children.  Gadget  parents 
perform  all  the  geometry  management  tasks  that  all  composite  widgets  perform,  described  in 
Chapter  11,  Geometry  Management.  Gadgets  also  follow  all  the  rules  of  normal  widget  chil 
dren.  However,  gadget  parents  also  have  the  added  responsibility  of  managing  the  overlap  of 
gadgets  or  making  sure  they  don't  overlap,  and  of  handling  events  for  the  gadgets  and  calling 
gadget  code.  This  section  describes  the  gadget-managing  role  of  the  gadget  parent 

The  Athena  SimpleMenu  widget  is  designed  to  manage  the  gadget  children  already 
described,  Sme,  SmeLine,  and  SmeBSB  (and  any  other  subclass  of  Sme  that  is  written  later). 
It  forms  a  vertical  menu  with  horizontal  panes.  It  is  quite  a  large  widget  because  it  contains 
all  the  geometry  management  code  in  addition  to  code  for  managing  events  for  the  gadgets. 
We'll  concentrate  just  on  the  code  that  manages  events  for  the  gadgets,  since  the  geometry 
management  code  is  as  described  in  Chapter  11,  Geometry  Management. 

Let's  begin  with  the  expose  method.  SimpleMenu' s  expose  method  does  no  drawing  of 
its  own.  It  simply  calls  the  expose  methods  of  the  gadget  children.  However,  it  compares 
the  region  passed  into  its  expose  method  to  determine  which  gadgets  need  redrawing. 
Example  12-11  shows  SimpleMenu's  expose  method. 
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Example  12-11.  SimpleMenu:  expose  method  calling  gadget  children's  expose  methods 

tdefine  ForAllChildren  (smw,  child?)  \ 

for  (  (childP)  "  (SmeObject  *)  (smw)  ->composite  .children  ;  \ 

(child?)  <  (SmeObject  *)  {  (smw)  ->composite  .children  +  \ 
(smw)  ->composite.num_children  )  ;   (childP)++  ) 

/*  ARGSUSED  */ 

static  void 

Redisplay  (w,  event,  region) 

Widget  w; 

XEvent  *  event; 

Region  region; 

{ 

SimpleMenuWidget  smw  =-•  (SimpleMenuWidget)  w; 

MenuEntryOb  ject  *  entry; 

MenuEntryOb  jectClass  class; 

if  (region  =  =  NULL) 
XClearWindow  (XtDisplay  (w)  ,  XtWindow  (w)  )  ; 

/* 

*  Check  and  Paint  each  of  the  entries  -  including  the  label. 
*/ 

ForAllChildren  (smw,  entry)  { 

if  (  IXtlsManaged  (  (Widget)  *entry)  )  continue; 

if  (region  !=  NULL) 

switch  (XRectlnRegion  (region,  (int)  (*entry)  ->rectangle  .x, 
(int)  (*entry)  ->rectangle  .y, 
(unsigned  int)  (*entry)  ->rectangle  .width, 
(unsigned  int)  (*entry)  ->rectangle  .height)  )  { 
case  Rectangleln: 
case  RectanglePart  : 

break; 
default: 

continue; 
} 
class  =  (MenuEntryOb  jectClass)  (  *entry)  ->ob  ject  .  widget_class; 

if  (class->rect_class  .  expose  !=  NULL) 

(class->rect_class  .  expose)  (  (Widget)  *entry,  NULL,  NULL) 


Note  that  this  expose  method  is  also  called  from  elsewhere  in  the  widget  code  (specifically, 
from  the  resize  and  geometry_manager  methods)  to  redraw  the  gadgets.  In  these 
cases,  the  region  passed  in  is  set  to  NULL,  and  the  method  clears  its  window  and  redraws  all 
the  gadgets. 

Also  note  how  this  expose  method  invokes  the  expose  methods  of  its  children.  All 
expose  methods  (and  in  fact  all  methods)  are  stored  in  the  class  structure,  not  the  instance 
structure.  Composite  widgets  keep  only  a  list  of  the  instance  structures  of  their  children. 
However,  one  field  in  each  instance  structure  points  to  the  class  structure  for  that  child.  This 
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is  the  widget_class  field  of  the  Object  instance  part.*  In  this  example,  the  entry 
counter  variable  is  a  pointer  to  the  gadget  ID  (opaque  pointer  to  the  instance  structure)  of  one 
of  the  children.  Another  variable,  class,  declared  as  a  pointer  to  the  SmeOb  jectClass 
class  structure  (the  expected  class  of  the  children),  is  set  to  the  widget_class  field  in  the 
instance  structure  of  one  of  the  children.  Then  the  expose  field  of  this  class  structure  is 
checked  to  see  if  it  is  NULL,  and  if  not  it  is  invoked. 

Note  that  the  class  of  the  children  is  hardcoded  in  this  method.  This  widget  can  manage  only 
Sme  widgets  and  its  subclasses. 

The  resize  method  of  SimpleMenu  must  resize  the  children  when  it  is  resized  itself. 
(Actually,  this  is  unlikely,  since  the  SimpleMenu  widget  itself  is  a  subclass  of  Shell  and  is 
therefore  not  managed  by  any  parent.)  This  method  is  invoked  only  when  the  user  resizes  the 
menu  using  the  window  manager.  Since  this  widget  has  the  authority  to  determine  the  geom 
etry  of  its  children,  it  can  simply  resize  them.  This  particular  resize  method  (shown  in 
Example  12-12)  simply  sets  their  width  to  be  the  same  as  its  own. 

Example  12-12.  SimpleMenu:  resize  method 

static   void 
Resize (w) 
Widget    w; 
{ 

SimpleMenuWidget    smw   =••    (SimpleMenuWidget )    w; 

MenuEntryOb ject    *    entry; 

if    (    !XtIsRealized(w)     )    return; 

ForAllChildren (smw,    entry)       /*    reset    width   of   all    entries.    */ 
if    (XtIsManaged(     (Widget)     *entry) ) 

(*entry) ->rectangle .width   =    smw->core .width; 

Redisplay (w,     (XEvent    *)    NULL,     (Region)    NULL); 
} 

Notice  that  this  resize  method  invokes  the  expose  method  (Redisplay)  because  the 
gadgets  don't  have  resize  methods,  and  will  not  redraw  themselves  in  response  to  their 
size  change.f 

Now  let's  look  at  SimpleMenu's  actions.  Their  only  purpose  is  to  call  the  gadgets'  actions 
when  the  appropriate  events  arrive.  These  actions  are  added  in  the  usual  way:  they  are 
declared  at  the  top  of  the  .c  file,  then  registered  with  an  action  list  that  is  entered  into  the 
class  structure  initialization,  and  then  defined.  One  of  the  three  actions  is  shown  in  Example 
12-13. 


*The  Core  instance  part  structure  (not  complete)  is  the  concatenation  of  the  instance  parts  of  the  three  superclasses 
Object,  RectObj,  and  WindowObj.  Therefore,  it  also  includes  a  widget_class  field.  Since  composite  widgets 
do  not  normally  need  to  invoke  the  methods  of  their  children,  you  shouldn't  need  to  access  this  field. 
fThe  gadget  children  could  have  re  si  ze  methods,  and  this  resize  method  could  call  the  children's  re  si  ze  meth 
ods.  The  gadget's  resize  methods  would  simply  call  their  expose  method.  However,  this  does  exactly  the  same 
thing  as  the  code  shown  while  being  more  complicated. 
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Example  12-13.  SimpleMenu:  the  Notify  action  routine 

/*  ARGSUSED  */ 

static  void 

Notify(w,  event,  params,  num_params) 

Widget  w; 

XEvent  *  event; 

String  *  params; 

Cardinal  *  num_params; 

{ 

SimpleMenuWidget  smw  =  (SimpleMenuWidget)  w; 

MenuEntryObject  entry  =  smw->simple_menu.entry_set; 

MenuEntryOb jectClass  class; 

if  (  (entry  ==  NULL)  ||  IXtlsSensitive ( (Widget)  entry)  )  return; 

class  =  (MenuEntryOb jectClass)  entry->ob ject . widget_class; 
(class->menu_entry_class. notify) (  (Widget)  entry  ); 
} 

This  action  determines  whether  the  chosen  entry  is  sensitive  and,  if  so,  calls  the  notify 
method  of  that  gadget.  As  described  above  in  the  section  on  the  gadget  children,  gadgets 
define  their  actions  as  methods  so  that  they  can  conveniently  be  called  by  their  parent  Since 
these  methods  are  stored  in  the  class  structure  not  the  instance  structure,  this  is  done  using 
the  technique  described  above  for  the  expose  method. 

Although  not  critical  to  its  handling  of  gadgets,  SimpleMenu  does  one  more  interesting  thing. 
It  registers  the  PositionMenuAction  action  in  the  global  application  action  list  (as 
opposed  to  the  internal  widget  action  list)  so  that  the  application  or  application-defaults  file 
can  refer  to  this  action  in  translation  tables  without  needing  to  register  the  action.  This  action 
can  be  triggered  by  any  type  of  event  in  the  widget  and  positions  the  menu  according  to  data 
in  the  event  type.  (SimpleMenu  has  a  resource  that  controls  whether  this  placement  process 
makes  sure  that  the  menu  is  not  off  the  screen.) 

A  widget  can  add  an  action  to  the  global  action  list  by  calling  xtAddAction  just  like  an 
application  would,  but  from  its  class_initialize  method. 
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This  chapter  describes  various  Xt  functions  that  have  not  been  treated  else 
where  in  the  book. 
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Miscellaneous  Toolkit 
Programming  Techniques 


This  chapter  discusses  various  Xt  facilities  that  didn't  fit  neatly  into  any  other  chapter.  Some 
of  them  are  nonetheless  quite  important  for  accomplishing  certain  tasks.  You  should  scan  the 
contents  of  this  chapter  to  familiarize  yourself  with  these  facilities  so  that  you  will  be  aware 
of  them  when  you  need  them. 

The  topics  covered  are  errors  and  warning  messages,  a  description  of  all  of  Xt's  macros,  the 
Core  accept_f  ocus  method,  how  to  interpret  key  events,  and  Xt's  facilities  for  memory 
management. 


Errors  and  Warnings 

There  are  several  broad  categories  of  errors  that  may  occur  in  Xt  applications.  One  is  the  X 
server  error,  which  is  a  form  of  event  that  tells  the  client  that  some  parameter  in  an  earlier 
request  was  illegal,  or  that  no  more  server  memory  is  available.  A  second  is  the  connection 
failure  error  generated  by  Xlib  when  the  connection  with  the  server  fails  (usually  due  to  a 
system  crash  or  network  interruption).  Xlib  provides  the  XSetErrorHandler  and 
XSetlOErrorHandler  functions  to  allow  the  application  to  provide  a  routine  to  handle 
these  two  types  of  errors.  Xt  provides  no  interface  to  these  routines — Toolkit  applications 
must  use  the  Xlib  routines  to  customize  these  error  handlers  (Xlib  uses  default  error  handlers 
when  the  application  does  not  use  these  routines  to  specify  them).  For  a  description  of  these 
error  handlers  and  the  routines  for  changing  them,  see  Volume  One,  Xlib  Programming  Man 
ual. 

A  third  category  is  made  up  of  error  and  warning  messages  that  Xt  reports  when  function 
parameters  are  specified  improperly,  when  a  translation  is  incorrectly  specified,  and  for  many 
other  reasons.  For  a  complete  listing  of  all  errors  and  warnings  that  can  be  generated  by  Xt, 
see  Volume  Five,  X  Toolkit  Intrinsics  Reference  Manual,  Appendix  D,  Standard  Errors  and 
Warnings.  Xt  provides  separate  parallel  routines  for  errors  and  for  warnings.  The  difference 
between  Xt  errors  and  Xt  warnings  is  that  errors  are  fatal  and  the  application  exits  after  print 
ing  the  error,  while  warnings  are  nonfatal  and  the  application  continues.  The  main  purpose 
of  these  facilities  is  to  generate  consistent  messages. 
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Two  levels  of  interface  are  provided: 

A  high-level  interface  that  takes  an  error  name  and  class  and  looks  the  error  up  in  an  error 
resource  database.  The  high-level  fatal  error  handler  is  invoked  by  a  call  to  xtError- 
Msg  or  xtAppErrorMsg;  the  high-level  nonfatal  error  handler  is  invoked  by  a  call  to 
XtWarningMsg  or  XtAppWarningMsg. 

A  low-level  interface  that  takes  a  simple  string,  which  is  printed  out  as  the  error  message. 
The  low-level  fatal  error  handler  is  invoked  by  a  call  to  xtError  or  xtAppError;  the 
low-level  nonfatal  error  handler  is  invoked  by  a  call  to  xt Warning  or  xtApp- 
Warning. 

The  high-level  functions  construct  a  string  to  pass  to  the  lower-level  interface.  Widget  or 
application  code  can  also  use  Xt's  error  and  warning  reporting  system.  For  example,  when  a 
resource  is  given  an  illegal  value  in  a  resource  file,  the  widget  or  application  can  report  the 
error  or  warning  to  the  user  (which  depends  on  whether  the  widget  or  application  can  con 
tinue  after  the  error — most  widgets  issue  only  warnings  and  then  fall  back  on  their  default 
value).  Unless  you  are  writing  a  widget  set  and  therefore  need  to  keep  track  of  an  extensive 
set  of  error  and  warning  messages,  you  should  use  the  low-level  handlers  because  they  are 
easier  to  use.  To  use  the  low-level  handlers,  you  specify  the  string  message  as  the  sole  argu 
ment  to  XtError  or  XtWarning. 

Contrary  to  what  you  might  expect,  the  high-level  handlers  xtErrorMsg  and  xt- 
WarningMsg  are  actually  harder  to  use  than  the  low-level  handlers.  You  must  pass  six 
arguments  to  the  calls  that  generate  the  errors  or  warnings,  and  then  to  take  advantage  of 
their  benefits  you  must  set  up  an  error  resource  database.  The  first  three  arguments  are  the 
name,  type,  and  class  of  the  error.  The  use  of  these  three  arguments  is  not  yet  standardized 
since  they  are  not  widely  used.  However,  in  Xt  itself,  the  name  identifies  the  error  message, 
and  the  type  identifies  the  task  that  was  in  progress  when  the  error  occurred  (or  the  section  of 
code).  The  class,  within  Xt,  is  always  XtToolkitError.  The  three  remaining  arguments 
of  XtErrorMsg  and  XtWarningMsg  are  a  default  message,  a  parameter  list,  and  the 
number  of  parameters.  The  default  message  will  be  printed  only  if  no  matching  message  is 
found  in  the  database.  Because  Xt  does  not  define  or  install  any  error  database,  it  uses  these 
default  messages  only,  and  ignores  the  name,  type,  and  class  information.  The  parameter  list 
is  used  together  with  the  message  in  the  database.  The  message  may  be  in  standard  printf 
format,  and  the  parameters  are  used  to  fill  in  any  variable  fields. 

Example  13-1  shows  one  of  the  rare  cases  where  XtErrorMsg  is  invoked  in  the  Athena 
widgets. 

Example  13-1.  How  to  invoke  XtErrorMsg  (from  AsciiSrc.c) 

if  (src->ascii_src . string  ==  NULL) 

XtErrorMsg ("NoFile",  "asciiSourceCreate",  "XawError", 

"Creating  a  read  only  disk  widget  and  no  file  \ 
specified. ", 
NULL,  0); 

The  error  resource  database  is  stored  in  a  file,  lusrlliblXHIXtErrorDB,  under  most  UNIX 
operating  systems.  Since  this  database  is  made  up  of  one  file,  you  must  append  the  resource 
settings  you  need  to  this  file  rather  than  replacing  it.  The  resource  name  searched  for  in  the 
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database  is  the  concatenation  of  the  name  and  type  arguments  specified  in  the  calls  to  xt- 
ErrorMsg  or  XtWarningMsg. 

You  can  redefine  the  routine  that  prints  the  message  in  order  to  change  the  fixed  part  of  the 
message  or  to  add  features  like  logging  of  errors  and  warnings.  Use  XtSetErrorMsg- 
Handler  and  xtSetWarningMsgHandler  (if  you  are  using  the  high-level  handlers) 
or  XtSetErrorHandler  and  XtSetWarningHandler  (if  you  are  using  the  low- 
level  handlers).  See  the  reference  pages  for  xtErrorMsgHandler(2)  and  xtError- 
Handler(2)  in  Volume  Five,  X  Toolkit  Intrinsics  Reference  Manual,  for  a  description  of 
how  to  define  a  new  error  or  warning  handler.  The  default  error  and  warning  messages 
printed  are: 


X  Toolkit   Error:      message. 
X  Toolkit   Warning:    message. 


(for  errors) 
(for  warnings) 


Remember  that  Xt  itself  uses  these  messages  (not  just  your  widget  code),  so  that  they  must 
remain  appropriate  when  called  from  anywhere  in  the  Xt,  widget,  or  application  code.  If  you 
want  the  message  to  identify  the  name  of  the  widget  set  or  widget,  you  must  include  this 
information  in  the  part  of  the  message  filled  in  from  the  string  you  pass  or  from  the  resource 
database. 

Table  13-1  summarizes  Xt's  calls  for  issuing  errors  and  warnings  and  for  modifying  the  mes 
sages  issued. 


Table  13-1.  Xt  Error  and  Warning  Message  Utilities 


Message 


Issue  Error 
Issue  Warning 
Set  Error  Handler 
Set  Warning  Handler 


Low  Level 


XtError 

XtWarning 

XtSetErrorHandler 

XtSetWarningHandler 


High  Level 


XtErrorMsg 
XtWarningMsg 
XtSetErrorMsgHandler 
XtSetWarningMsgHandler 


All  eight  of  these  calls  have  xt  App  equivalents,  as  described  in  Section  13.6. 

In  other  words,  all  the  error  and  warning  functions  have  application  context  versions  with  the 
same  name  but  with  App  inserted  after  xt  in  their  names.  Note,  however,  that  for  the  high- 
level  routines  that  use  the  error  and  warning  resource  database,  there  is  only  one  database 
common  to  all  application  contexts,  at  least  in  the  sample  implementation  of  Xt  provided  by 
MIT  under  R3  and  R4. 

When  writing  a  high-level  error  or  warning  handler  you  will  need  to  call  xtGetError- 
Database  to  get  a  pointer  to  the  error  resource  database  and  xtGetErrorDatabase- 
Text  to  get  the  message  for  a  particular  set  of  arguments  passed  to  XtErrorMsg  or  Xt 
WarningMsg.  For  details  on  how  to  use  these  functions,  see  the  reference  pages  in  Volume 
Five,  X  Toolkit  Intrinsics  Reference  Manual. 

xtStringConversionWarning  is  a  convenience  routine  to  be  used  in  resource  type 
converters  that  convert  from  xtRString  to  a  resource  type  not  defined  by  Xt.  It  calls  Xt 
WarningMsg  with  the  appropriate  arguments  to  issue  a  suitable  warning.  Note  however, 
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that  the  class  used  is  xtToolkitError.  It  would  probably  be  better  to  use  a  class  that 
describes  the  widget  or  widget  set  that  uses  the  converter. 


13.2  Macros  For  Getting  Widget  Information 

Xt  provides  several  macros  and  functions  for  getting  information  about  widgets.  Some  of 
these,  such  as  xtlsRealized  and  xtlsManaged,  you  have  seen  before  in  the  context 
of  widget  methods. 

Some  of  these  are  macros  and  some  are  functions,  and  some  are  macros  when  used  in  widget 
code  and  functions  when  used  in  application  code.  This  does  not  affect  how  they  can  be 
used,  so  we  won't  bother  to  specify  which  can  be  both  functions  and  macros.  We  will  use  the 
term  "macro"  for  all  of  these  informational  routines.  In  Volume  Five,  they  are  listed  alpha 
betically,  together  with  all  of  the  Intrinsics  functions. 

Xt  provides  two  macros  for  determining  the  class  of  a  widget  xtlsComposite  and  xt- 
is Subclass.  These  are  primarily  used  internally  by  Xt  to  implement  geometry  manage 
ment,  but  you  may  find  a  use  for  them.  For  example,  you  might  write  a  composite  widget 
that  uses  XtlsComposite  to  treat  composite  children  differently  than  simple  children,  or 
uses  xt  is  Subclass  to  treat  constraint  children  or  one  of  your  own  classes  uniquely. 

XtlsManaged  you  have  already  seen  used  in  composite  widgets.  See  Chapter  11,  Geome 
try  Management. 

You  have  also  already  seen  XtlsRealized  used  in  various  methods  to  make  sure  a  widget 
has  a  window  before  operations  are  attempted  on  the  window.  For  example,  the  expose 
method  calls  XtlsRealized  before  drawing  into  the  window. 

Xt  is  Sensitive  checks  the  value  of  the  XtNsensitive  resource  for  a  widget  and  its 
ancestors.  If  any  of  them  is  FALSE,  it  returns  FALSE.  Remember  that  sensitivity  controls 
whether  a  widget  responds  to  user  events. 

xtHasCallbacks  lets  you  tell  whether  a  widget  class  has  a  callback  of  a  certain  resource 
name,  and  whether  any  callback  functions  have  actually  been  added  to  it  It  returns  the 
enum  value  XtCallbackNoList  if  there  is  no  callback  list,  XtCallbackHasNone  if 
there  is  a  callback  list  with  no  functions  on  it,  and  xtCallbackHasSome  if  there  is  a  call 
back  list  containing  functions  pointers. 

xtNameToWidget  gets  the  widget  ID  for  the  specified  widget  instance  name.  Its  primary 
use  from  the  application  is  to  get  the  IDs  of  the  child  widgets  of  a  compound  widget  such  as 
Dialog,  so  that  their  resources  can  be  set  directly.  This  is  a  violation  of  the  rules  of  data  hid 
ing  however,  and  is  not  recommended.  In  widget  code,  it  is  used  to  provide  a  layer  of 
abstraction  so  that  widgets  can  be  identified  using  string  names. 

The  XtNameToWidget  function  takes  two  arguments,  reference  and  name.  The 
search  begins  from  the  widget  specified  in  the  re  ference  argument  and  works  down  the 
hierarchy.  The  name  argument  is  the  instance  name  of  the  child  being  searched  for,  possibly 
with  several  segments.  For  example,  for  a  simple  hierarchy  made  up  of  a  form  widget  as  the 
parent  of  a  box  widget  as  the  parent  of  a  command  button,  the  code  shown  in  Some- 
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Function  in  Example  13-2  shows  the  two  calls  that  would  return  the  IDs  of  the  two  widg 
ets. 

Example  13-2.  Getting  widget  IDs  with  XtNameToWidget 

Widget    form; 

main(argc,  argv) 
int  argc; 
char  **argv; 
{ 

Widget  box,  button; 

/*  create  form  */ 

box  =  XtCreateWidget ("box",    boxWidgetClass, 
form,     )  ; 

button   =   XtCreateWidget ("button",    commandWidgetClass, 
box,     )  ; 


SomeFunction  (  ) 
{ 

Widget  box,  button; 

box  =  XtNameToWidget  (form,  "box")  ; 

button  =  XtNameToWidget  (form,  "box.  button")  ; 


xtWindowToWidget  gives  you  the  X  window  ID  of  the  window  created  by  a  widget 
This  is  used  mainly  by  Xt,  but  you  may  find  a  use  for  it 


13.3  The  Keyboard  Focus  and  accept_focus  Method 

The  keyboard  focus  is  the  window  to  which  the  server  sends  keyboard  events.  The  window 
manager  controls  which  window  this  is.  Under  click-to-type  window  managers,  the  window 
that  was  most  recently  clicked  on  (usually  with  some  keyboard  key  held)  receives  the  key 
board  focus.  Under  a  real-estate-driven  or  pointer-following  window  manager,  the  keyboard 
focus  is  always  the  root  window,  and  this  results  in  keyboard  events  being  sent  to  the  applica 
tion  (and  to  the  individual  window)  the  pointer  is  currently  in.  In  any  case,  even 
click-to-type  window  managers  set  the  keyboard  focus  only  to  children  of  the  root  win 
dow — the  application  top-level  windows. 

The  Core  class  part  structure  includes  a  field  for  the  accept_f  ocus  method.  This  method 
lets  a  widget  set  the  keyboard  focus  to  one  of  its  children  when  it  gets  the  keyboard  focus.  A 
typical  example  is  an  application  that  wants  to  set  the  keyboard  focus  to  the  text  entry  child 
of  a  dialog  box  whenever  the  dialog  box  is  given  the  keyboard  focus  by  the  window  manager. 
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This  would  be  done  so  that  the  user  can  type  with  the  pointer  anywhere  in  the  dialog  widget 
instead  of  just  with  the  pointer  in  the  text  entry  widget. 

To  implement  this  example,  the  text  entry  child  would  need  an  accept_f  ocus  method 
that  would  set  the  keyboard  focus  to  itself  using  the  Xlib  call  xSetlnputFocus,  and  the 
dialog  box  would  need  an  accept_f  ocus  method  that  called  xtCallAcceptFocus 
on  the  text  entry  widget  child.  The  application  can  call  XtCallAcceptFocus  on  the  dia 
log  widget  in  response  toFocusln  events  to  start  this  process,  and  set  the  focus  back  to 
PointerRoot  on  FocusOut  events.*  For  details  on  these  events  and  how  to  set  the  key 
board  focus  with  XSetlnputFocus,  see  Volume  Two,  Xlib  Reference  Manual.  (The 
Athena  Dialog  widget  and  Text  widget  do  not  define  the  appropriate  accept_f  ocus 
methods  for  this  to  work.)  This  procedure  is  illustrated  in  Figure  13-1. 


Window  Manager  gives  keyboard 
focus  to  Dialog  widget 


Application  calls 

XtCallAcceptFocus 

on  Dialog 


Application  Code 


Xt  calls  Dialog's 

accept   focus  method 


Dialog  accept_focus  method 

calls  XtCallAcceptFocus 


Xt  Calls  Text's  accept_ 

method,  which  calls 

XtSetlnputFocus  to  set  the 

keyboard  focus  to  itself 


Xt  Intrinsics 


Figure  13-1.  Using  XtCallAcceptFocus  to  set  the  keyboard  focus  to  a  child  of  a  dialog  widget 


*XtCal  1  AcceptFocus  is  not  provided  in  MIT's  version  of  the  R3  Intrinsics.  It  may  be  present  in  some  vendor's 
versions  of  R3,  but  this  is  unlikely.  It  is  available  in  all  versions  of  the  R4  Intrinsics. 
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This  procedure  for  giving  the  child  of  Dialog  the  keyboard  focus  is  necessary  because  the 
application  can't  find  out  the  name  of  the  child  of  Dialog  that  should  have  the  focus  without 
breaking  widget  encapsulation  rules. 

The  accept_f  ocus  returns  a  Boolean  value  to  report  whether  it  succeeded  in  setting  the 
keyboard  focus,  and  XtCallAcceptFocus  returns  this  same  value. 

The  KtSetKeyboardFocus  function  can  be  used  to  redirect  keyboard  events  that  occur 
anywhere  within  a  dialog  box  to  a  child  of  the  dialog,  usually  a  text  entry  widget.  (This  func 
tion  affects  only  Xt's  event  dispatching,  and  is  independent  of  the  X  server  keyboard  focus, 
which  has  a  similar  but  more  widespread  effect.)  The  Dialog  widget  can  itself  call  this  func 
tion  instead  of  calling  XtCallAcceptFocus.  Dialog  can  also  provide  a  resource  or  pub 
lic  function  to  allow  the  application  to  control  it 


13.4  Keyboard  Interpretation 

Keyboard  handling  in  X  is  designed  so  that  you  can  write  a  program  that  will  operate  on  sys 
tems  with  widely  different  physical  keyboards.  To  accomplish  this,  there  are  several  layers 
of  mappings: 

•  The  first  mapping  is  between  physical  keys  and  keycodes  (a  number  for  each  key),  and 
varies  between  servers.  A  KeyPress  event  includes  only  the  keycode  and  information 
about  what  other  keys  and  buttons  were  being  held  at  the  time  of  the  keypress.  Programs 
that  interpret  keycodes  directly  will  operate  on  only  one  type  of  system. 

•  The  next  mapping  is  between  keycodes  and  keysyms,  which  are  symbolic  constants 
beginning  with  XK_  that  represent  the  meaning  of  a  key  press.  This  mapping  takes  into 
account  whether  Shift  or  other  modifier  keys  were  being  held  during  the  press.  Xlib  pro 
vides  the  routine  XLookupString  that  converts  the  keycode  in  a  key  event  to  the 
appropriate  keysym.  Portable  programs  use  keysyms  to  interpret  key  events.  The  key- 
code  to  keysym  mapping  is  server-wide.  It  can  be  changed,  but  this  is  normally  done 
only  to  accomplish  radical  changes  in  the  placement  of  keys  such  as  changing  a  QWERTY 
style  keyboard  to  DVORAK. 

•  The  final  mapping  is  between  keysyms  and  strings.  For  printing  characters,  XLookup 
String  also  returns  a  string  representation  of  the  interpretation  of  the  key  pressed.  For 
example,  if  the  key  marked  A  was  pressed  with  no  other  keys  held  down,  the  string 
returned  would  be  a.  A  text  entry  widget,  for  example,  would  append  this  string  to  the 
string  being  displayed,  but  modify  the  string  in  other  ways  to  handle  keysyms  that  do  not 
have  a  string  representation  such  as  XK_Backspace.   The  values  of  keysyms  are 
arranged  logically  so  that  all  printing  characters  have  a  particular  range. 

When  you  write  an  action  that  accepts  key  events,  you  will  usually  need  to  interpret  the 
meaning  of  the  key  pressed.  Xt  provides  its  own  interface  to  XLookupString:  xt- 
TranslateKeycode.  You  pass  several  fields  of  the  key  event  to  Xt  Trans  late- 
Keycode,  and  it  returns  the  keysym.  However,  xt Trans lateKeycode  does  not  return 
the  string  interpretation  of  the  key  event  that  would  be  returned  by  XLookupString.  If 
you  need  that  string,  you  will  have  to  call  XLookupString. 
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Xt  provides  Xt Trans lateKeycode  because  Xt  also  provides  routines  for  changing  the 
way  the  translation  returned  by  XtTranslateKeycode  is  done.  XtSetKey- 
Translator  allows  you  to  specify  your  own  procedure  to  convert  from  the  key  event 
information  to  a  keysym.  The  default  key  event  translation  procedure  isxtTranslate- 
Key,  and  so  you  can  restore  the  default  translator  if  necessary,  and  so  that  you  can  call  it 
from  your  own  translator  to  get  default  translations  (you  need  to  add  only  the  code  that 
makes  the  translations  not  done  by  the  default  translator).  See  xtKeyProc  in  Volume  Five, 
X  Toolkit  Intrinsics  Reference  Manual,  for  details  on  providing  a  key  event  translation  proce 
dure. 

Among  these  routines  for  modifying  the  interpretation  of  key  events  is  a  facility  for  changing 
the  handling  of  capitalization.  For  example,  most  keyboards  have  the  question  mark  (?)  sym 
bol  over  the  slash  (/)  symbol  on  one  key.  The  standard  case  converter  converts  a  press  of  this 
key  with  the  Shift  key  held  down  to  the  XK_question  keysym.  In  rare  cases  a  keyboard 
may  have  a  different  symbol  over  /  and  put  ?  somewhere  else.  Also,  some  keyboards  have 
two  or  more  symbols  on  a  single  key,  some  of  which  are  not  represented  at  all  by  standard 
keysyms.  The  case  converter  handles  these  situations.  The  case  converter  is  usually  called 
from  the  key  translator  described  above.  To  call  the  case  converter,  use  XtConvertCase, 
and  to  change  the  case  converter,  call  xtRegisterCaseConverter.  See  xtCase- 
Proc  in  Volume  Five,  X  Toolkit  Intrinsics  Reference  Manual,  for  details  on  writing  a  case 
converter  procedure. 

Note  that  the  translation  manager  uses  these  same  key  translation  and  case  converter  routines 
to  interpret  translation  tables.  Therefore,  make  sure  that  you  add  features  only  to  them,  keep 
ing  existing  features. 


13.5  Memory  Allocation 

Xt  provides  routines  for  performing  routine  memory  allocation  and  deallocation.  The  rou 
tines  XtMalloc,  XtCalloc,  xtRealloc,  and  XtFree  are  equivalents  of  the  standard 
C  routines  malloc,  calloc,  realloc,  and  free  but  they  add  error  checking  and 
reporting.  The  allocation  routines  make  sure  the  allocation  succeeded,  and  if  it  did  not,  they 
print  a  (fatal)  error  message.  XtFree  makes  sure  the  passed  pointer  is  not  NULL  before  cal 
ling  free. 

xt New  is  a  macro  which  allocates  storage  for  one  instance  of  the  passed  type  and  returns  a 
pointer.  For  example,  xtNew  (xtCallbackList )  allocates  storage  for  one  callback  list 
structure.  xtNewString  is  a  macro  that  allocates  storage  for  a  string,  copies  the  string 
into  the  new  storage,  and  returns  the  pointer.  For  example,  a  string  can  be  copied  into  new 
storage  using  the  following: 

static  String  buf [ ]  =  "How  do  you  do?"; 
String  p; 

p  =  XtNewString (buf ); 

After  this  sequence,  p  points  to  a  separate  string  that  contains  "How  do  you  do?"  Then  buf 
can  be  changed  without  affecting  p. 
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13.6  Application  Contexts 


The  introduction  to  application  contexts  in  Section  3.8  described  their  use  in  99  percent  of 
applications.  As  you  may  recall,  their  purpose  is  chiefly  to  attain  portability  to  certain  sys 
tems  that  do  not  provide  a  separate  address  space  for  each  process.  Xt  provides  parallel  ver 
sions  of  many  routines — one  that  uses  the  default  application  context,  and  one  that  has  an 
explicit  application  context  argument  To  acheive  the  desired  portability,  you  have  to  use  the 
versions  with  the  explicit  argument  Table  13-2  shows  the  complete  list  of  routines  that  have 
two  versions. 

Table  13-2.  Xt  Routines  That  Use  Default  and  Explicit  Application  Contexts 


Default 


( registering  functions ) 
XtAddActions 
XtAddConverter 
XtAddlnput 
XtTimeOut 
XtWorkProc 
(creating  shells) 

XtCreateApplicationShell 
( event  dispatching ) 
XtMainLoop 
XtNextEvent 
XtPeekEvent 
XtPending 
XtProcessEvent 
(error  and  warning  messages) 
XtError 
XtErrorMsg 
XtGetErrorDat abase 
XtGetErrorDatabaseText 
XtSetErrorHandler 
XtSetErrorMsgHandler 
XtSetWarningHandler 
XtSetWarningMsgHandler 
XtWarning 
XtWarningMsg 
(selection  timeouts) 
XtGet Select ionTimeout 
Xt Set Select ionTimeout 


Explicit 


XtAppAddActions 

XtAppAddConverter 

XtAppAddlnput 

XtAppTimeOut 

XtAppWorkProc 

XtAppCreateShell 

XtAppMainLoop 

XtAppNextEvent 

XtAppPeekEvent 

XtAppPending 

XtAppProcessEvent 

XtAppError 

XtAppErrorMsg 

XtAppGetErrorDat abase 

XtAppGetErrorDatabaseText 

XtAppSetErrorHandler 

XtAppSetErrorMsgHandler 

XtAppSetWarningHandler 

XtAppSetWarningMsgHandler 

XtAppWarning 

XtAppWarningMsg 

XtAppGet Select ionTimeout 
XtAppSet Select ionTimeout 


Note  that  XtCreateApplicationShell  and  XtAppCreateShell  have  names  that 
don't  follow  the  example  set  by  all  the  rest 
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Changing  an  application  from  the  default  application  context  to  explicit  arguments  is  mostly 
a  matter  of  global  changes.  However,  the  xt initialize  routine  must  be  substituted  for 
as  described  in  Section  3.8.  If  you  want  to  avoid  making  the  application  context  a  global 
variable,  you  can  use  the  widgetToApplicationContext  macro  as  the  application 
context  argument  in  these  functions. 

13.6.1  Multiple  Application  Contexts 

The  use  of  more  than  one  application  context  in  a  single  program  presents  possibilities  that 
you  might  wish  to  explore.  Having  more  than  one  application  context  in  the  same  program 
allows  you  to  have  one  program  that  when  run  looks  like  two  or  more  independent  programs. 
This  approach  saves  disk  space  and  memory  on  systems  that  don't  provide  shared  libraries, 
since  the  grouped  programs  can  share  a  single  copy  of  the  libraries.  In  Sun  View,  many  of  the 
basic  applications  were  grouped  in  a  single  binary  probably  for  this  reason.  The  Xlib  and  Xt 
libraries  are  quite  large.  For  example,  on  a  Sony  NWS -841  workstation,  the  executable 
image  of  a  "hello,  world"  application  written  with  Xt  uses  300K  of  disk  space.  One  of  the 
most  complicated  existing  X  applications,  xterm,  uses  450K  of  disk  space  on  this  system. 
Therefore,  the  various  libraries  account  for  about  two-thirds  of  the  disk  space  used,  even  for  a 
large  program. 

Having  two  application  contexts  makes  each  sub-application  more  separate  than  if  they  were 
just  under  different  top-level  Shell  widgets.  Each  widget  has  a  separate  action  list,  and  each 
application  context  has  a  separate  action  list.  When  the  translation  manager  looks  for  an 
action,  it  looks  in  the  widget  action  list  first,  and  then  the  application  context  action  list. 
Therefore,  each  sub-application  could  add  an  action  to  its  application  context  without  con 
flict  with  another  sub-application  adding  a  different  action  of  the  same  name. 

On  parallel  processing  machines,  each  separate  application  context  could  run  in  parallel. 
However,  it  is  difficult  to  write  portable  code  to  take  advantage  of  this,  since  each  architec 
ture  has  different  conventions  for  indicating  parallelisms  in  C  code. 

13.6.2  Rewriting  Xt  Main  Loop  for  Multiple  Application  Contexts 

To  use  multiple  application  contexts,  you  need  to  write  your  own  equivalent  of  xtMain- 
Loop  to  dispatch  events  to  your  multiple  application  contexts.  The  available  tools  are  xt- 
AppNextEvent, XtAppPeekEvent, XtAppPending,  XtAppProcessEvent,  and 
the  Xlib  functions  XFlush  and  XSync.  This  is  tricky,  because  you  don't  want  to  let  the 
dispatching  of  any  one  application  context  get  behind.  It  is  not  as  simple  as  dispatching 
events  from  each  application  context  in  a  cycle.  There  is  little  experience  in  how  this  should 
be  done  properly,  and  no  examples  in  the  distribution  from  MIT.  However,  hypothetically, 
the  following  describes  how  it  could  work. 

To  do  this  properly,  you  have  to  understand  how  Xlib's  network  optimization  works.  Xlib 
buffers  up  many  types  of  requests  and  sends  (flushes)  them  to  the  server  as  a  group.*  A  flush 


*  For  a  detailed  discussion  of  Xlib's  network  optimization  and  its  effects,  see  the  introduction  to  Volume  Zero,  X  Pro 
tocol  Reference  Manual. 
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is  most  commonly  caused  by  a  routine  such  as  xtNextEvent  or  xt AppNextEvent  that 
waits  for  an  event  if  none  are  available.  Because  XtNextEvent  and  xt  AppNextEvent 
wait  forever  for  an  event,  if  they  were  used  with  multiple  application  contexts  the  routine 
could  get  locked  waiting  for  events  in  one  application  context  while  the  user  types  frantically 
in  the  other. 

The  answer  is  to  use  XtAppPending  to  determine  whether  an  event  is  available  on  a  par 
ticular  application  context,  and  then  call  xtAppProcessEvent  if  there  is  an  event  to  pro 
cess.  Then  continue  to  do  the  same  on  each  other  application  context.  However,  this  alone  is 
not  enough.  Neither  XtAppPending  nor  XtAppProcessEvent  called  in  this  manner 
cause  Xlib's  buffer  of  requests  to  be  sent  to  the  server.  Therefore,  periodic  calls  to  xsync  or 
XFlush  are  necessary  to  flush  the  output  buffer.  The  difficult  part  is  to  call  these  enough  to 
flush  the  buffer  when  necessary,  but  not  so  much  as  to  eliminate  the  advantages  of  the  buffer 
ing.  There  is  no  ideal  solution  to  this  problem. 


13.7  Multiple  Top-level  Shells 

A  single  application  can  have  more  than  one  top-level  window.  In  other  words,  you  are  not 
restricted  to  containing  your  application's  entire  user  interface  in  a  single  rectangle.  If  you 
have  one  section  of  the  application  that  is  most  appropriate  as  a  long,  thin  vertical  window 
that  looks  like  a  long,  permanent  menu,  and  another  section  that  is  a  long,  horizontal  bar  such 
as  a  ruler,  each  of  these  could  be  a  separate  top-level  window.  That  way,  not  only  is  less 
screen  space  wasted  than  if  these  two  windows  were  placed  within  a  single  rectangle,  but  the 
user  can  move  the  two  windows  around  separately  using  the  window  manager.  The  user  can 
also  iconify  them  separately  when  not  needed. 

To  create  additional  top-level  application  shell  widgets,  you  call  xt Great e- 
ApplicationShell  or  xtAppCreateShell  (the  former  uses  the  default  application 
context,  while  the  latter  has  an  explicit  application  context  argument).  The  class  specified  in 
the  call  should  be  topLevelShellWidgetClass. 

As  you  may  know,  a  single  server  may  have  several  screens  attached.  At  present,  all  shells 
created  will  appear  on  the  default  screen.  There  is  no  way  for  the  application  to  specify  that 
a  shell  be  created  on  a  particular  screen,  but  then  again,  doing  this  is  usually  unwise  anyway 
because  not  many  users  actually  have  more  than  one  screen.  The  user  can  specify  which 
screen  is  considered  the  default  screen  using  the  -display  command-line  option. 
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13.8  Connecting  to  Multiple  Servers 

One  of  the  great  features  of  the  server-client  model  is  that  a  single  program  can  connect  to 
several  servers  to  display  on  the  screens  of  several  users.  For  example,  this  would  allow  you 
to  create  an  X  based  version  of  the  UNIX  utility  wall  in  which  one  user  can  make  a  message 
appear  on  all  user's  screens  throughout  a  network.  You  could  also  create  a  conferencing  pro 
gram  in  which  every  user  has  a  window  on  their  screen  in  which  they  can  type  and  view  typ 
ing  by  others  in  real  time,  and  their  typing  will  appear  in  all  the  other  user's  screens. 

The  Xt  application  opens  a  connection  with  a  server  using  xtOpenDisplay  (this  routine 
requires  an  explicit  application  context  argument).  Once  you  have  opened  the  connection, 
you  will  want  to  create  a  shell  widget  on  the  server's  default  screen  using  xtCreate- 
ApplicationShell  or  xtAppCreateShell.  Then,  you  create  widgets  for  each 
server  simply  by  using  the  appropriate  Shell  widget  as  parent  Thereafter,  xtAppMain- 
Loop  dispatches  events  from  all  the  connections  to  the  appropriate  widget 
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This  appendix  gives  an  overview  of  the  widgets  available  in  the  AT&T  and 
OSF/Motif  widget  sets.  It  gives  a  sense  of  the  look  and  feel  of  applications 
developed  with  each  set,  and  provides  the  inheritance  hierarchy  and  overview 
of  the  available  widgets. 

In  This  Appendix: 

The  AT&T  OPEN  LOOK  Widgets  403 

Application  Controls 404 

Command  Buttons 404 

Exclusive  and  Nonexclusive  Settings 406 

Analog  Controls 407 

Composite  Widgets 408 

Menus  and  Control  Areas  408 

General-purpose  Composite  Widgets 408 

Scrollbars  and  Scrollable  Windows  409 

PopUps  410 

Text  Widgets 413 

Drawing  Areas 413 

The  OSF/Motif  Widgets 413 

Application  Controls 416 

Command  Buttons 416 

Analog  Controls 417 

Composite  Widgets 417 

Menus  and  Control  Areas  417 

General  Purpose  Composite  Widgets  420 

Scrollable  Windows 421 

PopUps  422 

Text  Widgets 423 

Drawing  Areas 423 


This  section  provides  an  overview  and  comparison  of  the  widgets  in  MIT's  Athena  widget 
set,  AT&T's  OPEN  LOOK™  widget  set,  and  the  Open  Software  Foundation's  Motif™.* 

As  we've  already  discussed,  the  Athena  widgets  were  developed  to  test  and  demonstrate  the 
Xt  Intrinsics.  They  are  used  as  the  basis  for  some  of  the  standard  MIT  clients  and  many  pub 
lic  domain  applications,  but  are  not  expected  to  be  used  for  most  commercial  applications 
because  Xaw  is  not  a  complete  environment. 

A  number  of  vendors  have  developed  proprietary  widget  sets.  For  example,  Sony  Microsys 
tems  offers  S-windows,  a  widget  set  for  its  News  workstation.  However,  given  that  one  of 
the  purposes  of  widgets  is  to  provide  a  common  look  and  feel  for  X  applications,  it  is  natural 
that  there  should  be  a  shakeout  as  vendors  align  themselves  with  one  or  two  major  con 
tenders. 

As  it  has  turned  out,  the  two  major  contenders  for  a  graphical  user-interface  standard,  OPEN 
LOOK  and  Motif,  are  put  forth  by  the  two  major  contenders  for  an  underlying  UNIX  operating 
system  standard,  AT&T  and  the  Open  Software  Foundation. 

OPEN  LOOK  is  somewhat  unusual  in  that  it  started  out  not  as  a  set  of  widgets,  but  as  a  user- 
interface  specification.  The  specification,  originally  developed  by  Sun  Microsystems  with 
AT&T  backing,  was  widely  circulated  for  comment  before  any  implementations  were  begun. 
The  objective  was  to  develop  a  graphical  user-interface  standard  for  UNIX  worksta 
tions — one  that  would  be  implementation-independent,  and,  it  was  hoped,  implemented  sep 
arately  by  many  different  vendors. 

At  present,  the  two  major  implementations  of  OPEN  LOOK  are  Sun's  XView  toolkit  (which  is 
not  based  on  Xt,  but  instead  provides  an  application-programmer's  interface  similar  to  Sun's 
proprietary  Sun  View  windowing  system),  and  AT&T's  OPEN  LOOK  Xt-based  widget  set 
Both  of  these  toolkits  will  be  available  to  all  AT&T  UNIX  System  V  Release  4  licensees.  In 
our  discussions,  we  are  referring  specifically  to  AT&T's  OPEN  LOOK  toolkit,  which  does  not 
necessarily  include  every  OPEN  LOOK  feature.  Nor  should  its  implementation  be  considered 
the  only  way  to  provide  features  called  for  by  OPEN  LOOK. 


*OPEN  LOOK  is  a  registered  trademark  of  AT&T,  and  Motif  is  a  registered  trademark  of  Open  Software  Foundation. 
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The  Open  Software  Foundation's  Motif  toolkit  is  based  on  a  combination  of  widget  sets  orig 
inally  developed  by  two  OSF  sponsors,  Digital  and  Hewlett-Packard.  The  look  and  feel  of 
the  widget  set  was  proposed  by  HP/Microsoft  It  is  designed  to  emulate  the  look  and  feel  of 
the  IBM/Microsoft  Presentation  Manager  standard  widely  expected  to  be  adopted  in  the 
microcomputer  world. 

Motifs  API  (Application  Programmer's  Interface)  is  based  on  DECWindows.  Digital  also 
provided  Motif  with  some  underlying  enhancements  to  the  Xt  Intrinsics  (most  notably  a  form 
of  windowless  widgets  called  gadgets)  and  various  supporting  utilities. 

Table  A-l  compares  the  widgets  available  in  Athena,  AT&T  OPEN  LOOK  set,  and  Motif. 

Table  A-1.  Comparison  of  Athena,  OPEN  LOOK,  and  Motif  Widgets 
Simple  widgets  (mostly  controls): 


Athena 

OPEN  LOOK 

Motif 

Description 

Command 

OblongButton 

PushButton 

Invokes  a  command 

— 

— 

DrawnButton 

Invokes  a  command 

Toggle  (R4) 

ToggleButton 

RectButton 

Chooses  a  setting 

— 

CheckBox* 

— 

Alternate       way       of 

choosing  a  setting 

MenuButton  (R4) 

ButtonStack 

CascadeButton 

Invokes   a  menu,  dis 

plays  label 

— 

AbbrevStack 

— 

Invokes   a  menu,  dis 

plays  default 

— 

— 

ArrowButton 

Reverses    direction   of 

movement 

— 

ScrollingList* 

List 

Displays  a  list  of  select 

able  strings 

Scroll 

Scrollbar 

ScrollBar 

Scrolls      through      an 

associated  window 

— 

Slider 

Scale* 

Sets    (or   displays)   an 

analog  value 

Grip 

— 

— 

Resize  point  for  panes 

in  VPaned 

Label 

StaticText 

Label 

Displays  a  fixed  string 

Text 

Text 

Text 

Displays  editable  text 

— 

TextField 

Text 

Displays  a  single  line 

of  editable  text 

— 

— 

Separator 

Displays  a  line  or  other 

separator 

Pop  ups  (subclasses  of  shell): 


Athena 

OPEN  LOOK 

Motif 

Description 

SimpleMenu  (R4) 

Menu 
Notice 

MenuShell 
DialogShell 

Parents  a  popup  menu 
Displays       a      dialog 
requiring  input 
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Table  A-1.  Comparison  of  Athena,  OPEN  LOOK,  and  Motif  Widgets  (continued) 


Athena 

OPEN  LOOK 

Motif 

Description 

— 

Popup  Window 
Help 

— 

Displays  a  more  com 
plex  dialog 
Displays   a  help   win 
dow 

Composite  and  Constraint  Widgets: 


Athena 

OPEN  LOOK 

Motif 

Description 

— 

BulletinBoard 

BulletinBoard 

Free-form      placement 

area 

— 

— 

DrawingArea 

Free-form  drawing  area 

Box 

— 

— 

Displays     children    in 

order  added 

— 

ControlArea 

RowColumn 

Arranges    children    in 

rows  or  columns 

Form 

Form 

Form 

Manages  children  rela 

tive  to  each  other 

__ 

Exclusives 

— 

Makes  RectButton  chil 

dren  exclusive 

__ 

Nonexclusives 

— 

Makes  RectButton  chil 

dren  nonexclusive 

^___ 

FooterPanel 

— 

Provides  a  consistently- 

sized  message  area 

^_ 



Frame 

Gives  consistent  border 

to  enclosed  widgets 



ScrollingList* 

SelectionBox 

Provides    a    selectable 

list  of  strings,  plus   a 

text  area  for  entering  a 

new  value 



Command 

Provides    a    selectable 

list  of  commands 

_ 

FileSelectionBox 

Provides    a    selectable 

list  of  filenames 

__ 

Caption 

— 

Displays    a   label   and 

one  child  widget 

Viewport 

Scrolling  Window 

ScrolledWindow 

Displays    a    scrollable 

child  window 

MainWindow 

ScrolledWindow     with 

special  appearance 

VPaned 

_ 

PanedWindow 

Displays    panes    resiz 

able  in  one  direction 

*Checkbox,  ScrollingList,  and  Scale  are  technically  composite  widgets. 
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Comparable  widgets  share  a  line  in  the  table.  Widgets  for  which  no  equivalent  occurs  in  a 
given  set  are  indicated  by  a  hyphen  in  the  appropriate  column.  Note  that  comparisons  are 
approximate  only,  since  widgets  have  complex  behavior  that  may  distinguish  them  signifi 
cantly  from  another  widget  with  an  ostensibly  similar  purpose. 

The  following  sections  provide  an  overview  of  the  widgets  available  in  the  OPEN  LOOK  and 
Motif  widget  sets.  Throughout,  we  contrast  them  with  the  Athena  widgets,  which  have  been 
used  as  examples  in  this  book,  to  give  you  an  idea  of  the  additional  features  provided  by  the 
commercial  widget  sets. 

Keep  in  mind  that  the  look  and  feel  of  an  application  is  controlled  by  the  window  manager  as 
well  as  by  the  widget  set.  Both  AT&T  and  OSF  supply  window  managers  to  complement 
their  widgets. 

Note  that  there  may  be  additions  to  the  basic  X  Toolkit  API  as  well. 

In  the  AT&T  OPEN  LOOK  widget  set,  these  API  additions  are  rather  minor.  There  is  one 
essential  function,  Olinitialize,  which  sets  initial  values  needed  by  other  routines,  and 
by  certain  widgets.  Olinitialize  creates  a  base  window,  which  from  the  programmer's 
point  of  view  is  identical  to  the  Intrinsics-supplied  TopLevelShell  widget  class,  but  which 
automatically  handles  certain  features  of  the  OPEN  LOOK  interface.  There  are  also  several 
convenience  functions,  mostly  having  to  do  with  conversions  between  pixel  sizes  and  various 
standard  units.  More  importantly,  there  is  a  facility  for  registering  help  screens  for  each  ele 
ment  in  an  application. 

Motif  has  made  more  extensive  API  additions,  modifying  all  of  the  base  widget  classes,  and 
other  Intrinsics  features.  For  example,  all  resources  are  referred  to  by  names  beginning  with 
xmN  or  xmC  rather  than  the  familiar  xtN  and  xtc.  In  Chapter  12,  we  mentioned  Motifs 
support  for  windowless  widgets,  or  "gadgets."  (Both  MIT's  Release  4  of  Xt  and  AT&T's 
latest  release  of  its  OPEN  LOOK  toolkit  also  support  gadgets.) 

In  addition,  Motif  makes  heavy  use  of  convenience  functions.  Rather  than  using  xt- 
CreateManagedWidget  to  create  each  widget,  there  is  a  separate  creation  routine  for 
each  widget.  In  some  cases,  a  convenience  routine  creates  more  than  one  widget  Rather 
than  using  separate  calls  to  XtCreatePopupShell  and  XtCreateManagedWidget 
to  create  a  pop-up  shell  and  the  dialog  box  it  displays,  you  might  call  a  function  such  as  Xm- 
CreateMessageDialog  to  create  both  widgets  at  once.  Some  convenience  routines  cre 
ate  special  configurations  of  a  single,  complex  widget  (e.g.,  a  composite  widget  with  specific 
children.) 

Motif  also  uses  call  data  extensively.  Almost  every  widget  has  a  struct  defined  as 
widgetclassCallbackStruct  (e.g.,  XmToggleButtonCallbackStruct). 
This  struct  contains  different  fields  for  each  widget,  but  each  contains  a  field  called  rea 
son.  The  reason  field  defines  which  callback  has  been  called.  So  using  this  feature 
allows  you  to  have  a  single  piece  of  code  to  handle  all  callbacks  for  a  widget. 

In  Motif's  version  of  the  Intrinsics,  the  search  path  for  resources  has  been  expanded  to  sup 
port  language-specific  resource  defaults  (to  support  internationalization  of  applications). 

Both  Motif  and  OPEN  LOOK  offer  clear  advantages  over  Xaw.  Unfortunately,  however,  the 
choice  of  which  one  to  use  may  depend  on  company  marketing  goals  and  politics  rather  than 
on  clear  technical  merit.  We  encourage  independent  developers  to  try  both  and  to  base  your 
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opinions  on  the  ease  of  programming  and  the  preferences  of  your  users,  rather  than  on  mar 
keting  hype  by  one  side  or  the  other.  Eventually,  there  will  be  one  common  set  of  widgets, 
with  resources  to  provide  the  appropriate  look  and  feel  (in  conjunction  with  the  window 
manager). 


A.1   The  AT&T  OPEN  LOOK  Widgets 


Figure  A-l  shows  the  overall  look  and  feel  of  an  OPEN  LOOK  application. 

title 


pane 


footer 
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Z3 
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New  Document                                        Page  One 

b 

resize  corner 


—  vertical  scrollbar 


horizontal  scrollbar 


Figure  A-1.  An  OPEN  LOOK  application 


The  base  window  of  an  application  always  has  these  elements: 

•  A  title  bar,  or  header,  with  a  title  supplied  by  the  application  centered  in  the  bar.  The  title 
might  be  the  application  name,  or  the  name  of  a  file  being  edited.   If  the  application 
doesn't  provide  a  title,  the  title  bar  displays  the  string  "Untitled." 

•  A  "window  mark"  on  the  left  side  of  the  title  bar.  If  the  user  clicks  on  this  mark  with  the 
first  (leftmost)  pointer  button,  the  window  closes. 

•  A  window  menu,  that  comes  up  automatically  when  you  click  on  the  title  bar  with  the 
third  (rightmost)  pointer  button. 

•  One  or  more  panes  for  input  and  display  of  application  data. 

•  One  or  more  control  areas,  containing  buttons  that  invoke  application  actions  or  menus 
containing  additional  actions.  Control  areas  can  be  horizontal,  vertical,  or  both. 
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Optional  elements  include  resize  corners  (which  allow  the  user  to  resize  the  application  by 
dragging  them  with  the  first  pointer  button),  horizontal  and/or  vertical  scrollbars,  and  a  footer 
area  for  displaying  messages. 

Some  of  these  elements  do  not  correspond  to  widgets,  but  are  produced  by  the  OPEN  LOOK 
window  manager,  olwm,  as  window  decoration.  For  example,  the  header,  including  title  bar, 
window  mark  and  window  menu,  are  provided  by  the  window  manager,  as  are  the  optional 
resize  corners.  However,  control  areas,  panes,  scrollbars,  and  the  footer  area  do  correspond 
to  particular  widgets. 

In  addition  to  base  windows,  applications  may  have  several  kinds  of  pop  up.  Both  drop 
down  and  pure  pop-up  menus  are  supported,  as  well  as  several  standard  kinds  of  notices  and 
dialogs.  Probably  OPEN  LOOK'S  best-known  feature  is  the  "pushpin"  metaphor  that  allows 
frequently-accessed  pop-up  menus  to  be  kept  on  the  screen  rather  than  hidden  again  after 
they  have  been  used. 

The  following  sections  discuss  some  of  the  widgets  AT&T  has  provided  to  support  the  OPEN 
LOOK  user  interface.  Figure  A-2  shows  the  overall  widget  inheritance  hierarchy. 

Note  that  there  are  a  number  of  widgets  that  are  never  instantiated  by  the  application  pro 
grammer,  but  are  used  by  other  widgets.  For  example,  the  checkbox  is  actually  a  composite 
widget  that  manages  a  check  widget  as  its  child!  The  Pushpin  used  in  pop  ups  and  the  Mag 
nifier  used  in  Help  windows  (and  the  Help  window  itself)  are  examples  of  other  widgets  that 
are  not  instantiated  directly. 

A.1.1    Application  Controls 

Most  applications  will  have  at  least  one  control  area,  with  pointer-selectable  buttons  that 
invoke  commands  or  menus,  or  choose  settings. 

One  of  the  areas  where  OPEN  LOOK  clearly  stands  out  over  the  Athena  widgets  is  in  the  rich 
set  of  controls  it  provides.  Athena  has  one  kind  of  Command  widget;  OPEN  LOOK  has  six. 

A.1.1 .1    Command  Buttons 

The  Athena  Command  widget  implements  one  of  the  most  basic  user-interface  idioms — a 
button  that  invokes  an  action  when  you  click  on  it  with  the  pointer.  In  R4,  the  Athena  widg 
ets  include  a  subclass  of  Command,  the  MenuButton  widget,  which  includes  code  for  placing 
a  pop-up  menu. 
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*  New  in  Release  2  of  OpenLook  Toolkit 


Figure  A-2.  Class  inheritance  hierarchy  of  the  AT&  TOPEN  LOOK  widgets 

The  OPEN  LOOK  widget  set  implements  similar  functions  using  the  OblongButton  and 
ButtonStack  widgets.  Figure  A-3  shows  a  Control  Area  containing  OblongButton  and 
Buttons  tack  widgets. 
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Figure  A-3.  An  OPEN  LOOK  ControlArea  with  OblongButton  and  ButtonStack  widgets 

The  OblongButton  widget  provides  many  niceties  lacking  from  the  Athena  Command 
widget.  One  of  the  most  important  is  that  OblongButton  has  a  resource  that  allows  one  but 
ton  among  several  to  be  designated  as  the  default,  in  which  case  it  is  bordered  by  a  double 
line,  to  give  the  user  immediate  visual  feedback  about  which  button  to  choose  when  several 
are  available. 

The  OblongButton  also  has  the  notion  of  a  "busy"  state  in  which  it  cannot  perform  the  action 
because  it  is  already  doing  it.  (This  is  different  from  a  widget  that  is  insensitive  (meaning  its 
function  is  unavailable),  though  in  practice,  the  effect  is  quite  similar.)  The  label  and  border 
of  an  insensitive  button  are  dimmed;  the  background  of  a  busy  button  is  filled  with  a  stippled 
pattern. 

The  ButtonStack  widget  is  similar  to  the  OblongButton,  but  invokes  a  menu  rather  than  a 
single  command.  Clicking  on  it  with  one  button  (usually  Button  3)  pops  up  a  menu  (which 
may  in  turn  include  other  ButtonStack  widgets,  for  cascading  pop  ups.)  Clicking  on  it  with 
another  button  (usually  Button  1)  activates  the  default  item  for  the  menu.  Visually,  a  Button- 
Stack  is  differentiated  from  an  OblongButton  by  the  presence  of  an  arrowhead,  pointing  in 
the  direction  that  the  menu  will  pop  up.* 

In  addition,  there  is  an  AbbrevStack  widget,  which  performs  similar  functions  as  the  Button- 
Stack  widget,  but  shows  up  only  as  a  small  unlabelled  box,  with  the  default  choice  for  the 
menu  displayed  beside  it. 

A.1 .1 .2    Exclusive  and  Nonexclusive  Settings 

In  R3,  the  Athena  widget  set  lacks  the  concept  of  a  button  that  establishes  a  setting  (for 
example,  sets  an  application  resource)  rather  than  performs  an  action.  There  is  nothing  to 
keep  the  programmer  from  using  a  Command  widget  for  this  purpose,  but  if  so,  an  important 
user-interface  distinction  fails  to  be  made.t 

In  contrast  to  OblongButton,  which  always  indicates  that  an  action  will  be  performed,  a  Rect- 
Button  indicates  that  an  option  setting  will  be  chosen.  This  setting  may  be  exclusive  or 
nonexclusive.  This  is  not  determined  by  the  RectButton  widget  itself,  but  depends  on 
whether  the  widget  is  managed  by  an  Exclusives  or  Nonexclusives  composite  widget.  The 


*In  an  earlier  implementation  of  the  toolkit,  a  ButtonStack  widget  had  a  double  border  on  its  bottom  half,  giving  it 
the  appearance  of  a  stack  of  regular  buttons.  Hence  its  name,  which  is  now  merely  historical. 
fR4  Xaw  adds  a  Toggle  widget  for  this  purpose. 
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RectButton  widget  class  will  not  work  correctly  unless  managed  by  one  of  these  two  compo 
site  widgets.  The  Exclusives  and  Nonexclusives  widgets  are  themselves  usually  children  of  a 
Menu  or  ControlArea  widget 

In  an  Exclusives  widget,  RectButton  widgets  are  laid  out  side  by  side  in  one  or  more  col 
umns.  One  or  none  of  the  RectButton  widgets  is  chosen  as  the  default,  which  is  indicated  by 
a  double  border.  Once  a  RectButton  is  selected,  it  is  shown  with  a  dark  border.  The  Exclu 
sives  widget  makes  sure  that  no  more  than  one  RectButton  is  selected  at  a  time. 

In  a  Nonexclusives  widget,  RectButtons  are  displayed  with  separation  between  each  button. 
As  when  used  in  an  Exclusives  widget,  a  dark  border  indicates  that  the  option  has  been  cho 
sen.  However,  more  than  one  button  may  be  chosen  at  a  time. 

Figure  A-4  shows  examples  of  exclusive  and  nonexclusive  settings  on  menus.  Note  that,  like 
the  OblongButton,  a  RectButton  may  display  a  pixmap  instead  of  a  label.  This  makes  it  use 
ful  for  a  palette  in  a  paint  program. 
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Figure  A-4.  OPEN  LOOK  RectButtons  controlled  by  Exclusives  and  Nonexclusives  widgets 

The  CheckBox  widget  provides  an  alternate  way  to  display  nonexclusive  settings  to  the  user. 
It  displays  a  small  box  next  to  the  label,  and  displays  a  checkmark  in  the  box  when  the  option 
is  selected.  Checkboxes  appear  in  ControlAreas,  rather  than  on  menus.  Figure  A-5  shows 
examples  of  CheckBox  widgets. 
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Figure  A-5.  An  OPEN  LOOK  ChockBox  widget 


A. 1.1. 3    Analog  Controls 

In  addition  to  the  various  kinds  of  buttons  outlined  above,  OPEN  LOOK  provides  an  analog 
control  called  a  Slider.  A  Slider  widget  is  used  analogously  to  a  Scrollbar,  but  is  used  for  set 
ting  a  numeric  value.  Figure  A-6  shows  a  Slider  widget 
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Figure  A-6.  An  OPEN  LOOK  Slider  widget 


A.1.2   Composite  Widgets 

Composite  widgets  are  in  many  ways  the  most  important  widgets  in  any  widget  set  They 
define  the  way  that  widgets  work  together,  and  they  give  consistency  to  an  application. 

A.1 .2.1    Menus  and  Control  Areas 

As  we've  already  discussed,  command  buttons  of  any  kind  are  usually  displayed  as  part  of  a 
menu  or  control  area. 

Menus  can  either  pop  up  below  a  ButtonStack  or  an  AbbrevStack,  or  if  the  button  is  itself 
displayed  on  a  menu,  to  the  right,  in  a  menu  cascade.  Figure  A-4  showed  examples  of  menus. 

The  Menu  widget  is  a  pop-up  widget  created  with  xtCreatePopupShell.  It  has  a 
single  child,  which  is  a  ControlArea  widget 
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The  ControlArea  widget  places  its  children  in  rows  or  columns.  Resources  allow  the  applica 
tion  to  specify  a  fixed  width  and/or  height,  or  a  fixed  number  of  rows  or  columns.  Control- 
Area  widgets  are  usually  used  as  the  parent  of  OblongButton,  Buttons  tack,  Exclusives  or 
Nonexclusives  widgets  (which  in  turn  manage  RectButton  widgets,  as  described  in  the  next 
section). 

A.1 .2.2    General  Purpose  Composite  Widgets 

We've  already  discussed  the  Composite  widgets  relating  to  control  areas  and  menus.  How 
ever,  there  are  several  general-purpose  composite  widgets  in  the  OPEN  LOOK  set  as  well. 

The  BulletinBoard  widget  provides  a  free-form  area  for  placing  subwindows.  Widgets  can 
be  placed  on  a  BulletinBoard  at  arbitrary  x  and  y  coordinates;  if  no  coordinates  are  specified, 
they  appear  in  the  upper  left  corner.  The  BulletinBoard  provides  no  management  of  its  chil 
dren,  and  is  often  used  to  estabish  the  base  frame  for  an  application,  since  it  allows  the  appli 
cation  programmer  to  place  the  major  components  of  the  application,  rather  than  having  to  go 
by  some  Composite  widget's  arbitrary  placement  decisions. 

A  BulletinBoard  is  often  used  as  the  main  window  of  an  application. 

The  Form  widget  is  a  constraint  widget  similar  to  the  Athena  Form  widget  It  allows  the 
placement  of  widgets  to  be  specified  relative  to  each  other,  and  with  rules  governing  their 
separation  or  relative  position. 

The  Caption  widget  is  like  an  Athena  Label  widget  turned  inside  out.  Like  the  Label  widget, 
it  prints  a  string.  However,  while  the  label  widget's  string  is  printed  inside  a  visible  widget 
border,  a  Caption  string  appears  outside  a  bordered  area.  Caption  is  a  composite  widget 
class,  and  its  label  typically  refers  to  a  child  widget  of  any  size,  which  the  Caption  widget 
manages.  The  label  can  be  aligned  on  either  the  right,  left,  top  or  bottom  of  the  child  widget. 

The  FooterPanel  widget  provides  a  consistent  method  for  placing  a  footer  along  the  bottom 
of  another  window.  The  footer  panel  takes  two  children.  The  top  child  is  typically  the  main 
composite  widget  of  the  application;  the  bottom  widget  may  contain  a  control  or  message 
area.  The  basic  feature  of  the  FooterPanel  widget  is  that  when  the  widget  is  resized,  it 
applies  all  the  change  in  the  vertical  direction  to  the  top  child,  maintaining  the  bottom  child 
at  a  constant  height 

A.1 .2.3    Scrollbars  and  Scrollable  Windows 

OPEN  LOOK  scrollbars  use  the  visual  metaphor  of  an  elevator  on  a  cable,  but  functionally 
they  are  similar  to  the  Athena  Scroll  widget  The  drag  area  (the  thumb  in  an  Athena  Scroll 
widget)  doesn't  change  size;  instead,  as  shown  in  Figure  A-7,  there  is  a  separate  area  that 
indicates  the  proportion  of  the  data  that  is  currently  being  displayed. 
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Figure  A-7.  An  OPEN  LOOK  Scrollbar 


Scrollbars  may  be  oriented  either  horizontally  or  vertically. 

Scrollbars  are  used  as  a  component  of  a  ScrolledWindow  widget,  which,  like  the  Athena 
Viewport  widget,  provides  a  scrollable  view  of  a  data  area  in  a  child  widget.  The  child 
widget  is  typically  larger  than  the  view  area,  but  only  the  area  in  the  parent's  view  area  can 
be  seen  at  any  one  time.  Figure  A-l  showed  a  ScrolledWindow  widget  as  the  main  applica 
tion  pane.  The  ScrollingList  widget  displays  a  scrollable  list  of  editable  text  fields,  and  pro 
vides  facilities  for  choosing  and  displaying  one  of  the  fields  as  "currently  selected."  Items 
can  be  selected  from  the  list,  changed,  copied,  and  so  on.  This  widget  is  useful  for  providing 
an  interface  to  select  a  file  for  reading  or  writing. 

Figure  A-8  shows  a  ScrollingList  widget. 
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Figure  A-8.  An  OPEN  LOOK  ScrollingList  widget 


A.  1.3    Pop  Ups 


In  addition  to  Menu  widgets,  the  OPEN  LOOK  widget  set  contains  three  other  special  types  of 
pop-up  widgets:  Notices,  PopupWindows,  and  Help  windows. 

A  Notice  is  used  to  request  confirmation  or  other  information  from  the  user.  The  widget  con 
tains  a  text  area,  where  the  message  to  the  user  is  displayed,  and  a  control  area  containing 
one  or  more  buttons,  one  of  which  must  be  the  default  button. 

Figure  A-9  shows  an  OPEN  LOOK  Notice  widget 
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Figure  A-9.  An  OPEN  LOOK  Notice 

A  Notice  grabs  the  pointer.  The  only  input  allowed  is  to  the  Notice.  Once  the  user  has 
clicked  a  button,  the  Notice  disappears. 

The  second  special  pop-up  type  is  a  PopupWindow,  which  can  be  used  for  more  complex  pop 
ups.  Unlike  a  Notice,  which  is  a  subclass  of  OvenideShell,  a  PopupWindowShell  is  a  sub 
class  of  WMShell,  and  so  is  decorated  by  the  window  manager.  It  has  all  the  visual  attributes 
of  a  top-level  window,  including  resize  corners,  etc.  In  addition,  it  displays  a  pushpin  in  the 
upper  left  corner.  If  the  user  clicks  on  the  pushpin  with  the  pointer,  the  menu  doesn't  go 
away  when  its  action  has  been  performed,  but  stays  on  the  screen.  This  allows  the  user  to 
keep  menus  (and  other  frequently-referenced  pop  ups,  such  as  help  screens)  "pinned"  on  the 
display,  where  they  can  be  moved  like  regular  windows.  (Menus  can  also  display  a  pushpin; 
its  presence  or  absence  is  controlled  by  a  widget  resource.) 

A  PopupWindow  typically  contains  an  upper  control  area  that  may  include  menus,  and  a 
lower  control  area  that  may  be  used  for  buttons  invoking  widget  actions.  Resources  allow  for 
automatic  creation  of  several  buttons,  including  a  "reset  to  factory"  button,  a  "set  defaults" 
button,  and  several  other  ways  of  setting  standard  properties  for  an  application. 

Figure  A- 10  shows  a  PopupWindow. 
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Figure  A-10.  An  OPEN  LOOK  Popup  Window 

A  Help  window  is  not  instantiated  in  the  usual  way.  Instead,  an  application  uses  the 
OlRegisterHelp  function  to  register  help  text  with  the  toolkit.  Text  can  be  associated 
with  a  widget  class,  a  widget  instance,  or  a  window.  When  the  user  clicks  the  second  pointer 
button  on  an  object,  the  Help  widget  is  automatically  displayed  by  the  toolkit.  The  Help 
widget  includes  a  Magnifier  subwidget,  which  displays  a  magnifying  glass  containing  an 
image  of  the  part  of  the  screen  on  which  the  user  clicked  the  pointer.  Figure  A- 11  shows  a 
Help  window. 
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Figure  A-11.  An  OPEN  LOOK  Help  window 
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A.  1.4   Text  Widgets 

OPEN  LOOK  offers  three  separate  text  widgets.  The  StaticText  widget  is  similar  to  the 
Athena  Label  widget,  in  that  it  displays  a  fixed  text  string.  However,  it  can  handle  longer 
strings  by  using  wordwrapping  to  break  the  string  onto  multiple  lines. 

The  OPEN  LOOK  Text  widget  is  very  similar  to  the  Athena  Text  widget.  It  provides  a  gen 
eral-purpose  editable  text  widget,  with  editing  commands  customizable  via  a  translation 
table. 

One  of  the  great  weaknesses  of  the  Athena  Text  widget  is  that  it  is  difficult  and  inefficient  to 
use  as  a  single-line  editable  field.  (A  program  can  add  translations  for  the  Return  key  to  limit 
the  text  to  a  single  line.)  OPEN  LOOK  addresses  this  need  with  the  TextField  widget,  useful 
for  developing  form  driven  applications.  TextField  widgets  were  shown  in  Figure  A-l  1. 

The  TextField  widget  provides  simple  editing  commands,  and  scrolling  if  the  string  is  too 
long  to  be  displayed.  When  the  keyboard  focus  leaves  the  widget,  or  when  the  Tab  or  Return 
key  is  pressed,  it  passes  the  data  in  the  field  to  the  application  for  validation. 


A. 1.5   Drawing  Areas 

Like  the  Athena  widget  set,  the  AT&T  OPEN  LOOK  widgets  provide  no  widget  explicitly 
labeled  as  a  drawing  area.  As  described  in  this  book,  one  is  expected  either  to  create  a  cus 
tom  widget  for  an  application's  main  window,  or  to  use  a  very  basic  widget  class,  and  add 
actions  for  drawing. 

The  AT&T  OPEN  LOOK  widget  set  does  include  a  Stub  widget  class  (which  is  not  docu 
mented  in  the  manual,  but  is  included  in  the  source)  which  is  useful  for  providing  a  window 
for  drawing. 


A.2  The  OSF/Motif  Widgets 

Figure  A-12  shows  the  general  look  of  a  Motif  application,  the  Motif  Reference  Editor,  mre. 
mre  was  developed  by  Mitch  Trachtenberg  and  is  OSF  demo  software  available  as  part  of  the 
Motif  distribution. 
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Figure  A- 12.  Look  and  f&el  of  a  Motif  application 

As  with  the  AT&T  OPEN  LOOK  widget  set,  some  of  the  features  of  a  main  application  win 
dow  are  actually  decoration  provided  by  the  window  manager,  mwm.  As  shown  in  Figure 
A- 12,  these  include  the  title  bar,  which  displays: 

•  The  title  provided  by  the  application. 

•  A  Menu  button,  which  drops  down  a  menu  containing  basic  window  manipulation  com 
mands. 

•  A  "Minimize"  button,  which  iconifies  the  application. 

•  A  "Maximize"  button,  which  causes  the  application  window  to  fill  the  entire  screen. 
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You  will  also  recognize  Motifs  version  of  many  of  the  common  controls  discussed  in  the 
section  on  the  AT&T  OPEN  LOOK  widget  set 

Figure  A- 13  shows  the  inheritance  hierarchy  of  the  Motif  widgets.  The  Intrinsics-supplied 
widget  classes  are  shaded  grey. 


1   Core 

I 

r                                 n 

Primitive              !  Cora 

)0site            Shell 

| 

I        '            i 

1                 \                i 

\  Label  1           Scrollbar           ]  Text 

OvemdeSheil               WMShell     j 

MenuShelF  |            VeodorShell 

|  List  |     1  Separator       ArrowButton 

1 

1                                I                1 

1                              1 

Drawn-      Push-    j  Toggle-    Cascade- 
Button      Button  jj  Button       Button 

TopLevelSbeil       TransiemShell 

1                 L 

Cons 

AppficationShell          DialogShell 

rrairtt 

~Ma~r 

lager 

T                                    "j" 

1                               1 

ScrolledWindow  |      PanedWindow 

[  Frame            [  RowColumn  [ 

Scale                  DrawingArea             BulletinBoard 

MainWindow                   j 

i 

Form  |        SelectionBox         MessageBox 

_    L  .-—  . 

j—                               _| 

Command]       j  FileSelectionBox  | 

Figure  A- 13.  Class  inheritance  hierarchy  of  the  Motif  widget  set 

The  Primitive  and  Manager  widgets  are  not  generally  instantiated  and  exist  only  to  provide 
resources  and  other  features  inherited  by  other  widgets. 

In  addition,  Motif  supports  a  Gadget  class,  which,  as  described  in  Chapter  12,  is  subclassed 
from  RectObj  rather  than  Core.  Gadget  equivalents  exist  for  the  Label  widget,  some  classes 
of  Button  widgets,  and  the  Separator  widget  Gadgets  are  not  shown  in  Figure  A- 13. 
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A.2.1    Application  Controls 

Like  OPEN  LOOK,  Motif  has  a  much  richer  set  of  application  controls  than  Athena. 
A.2.1 .1    Command  Buttons 

Motifs  PushButton  is  equivalent  to  Athena's  Command  widget  and  OPEN  LOOK'S  Rect- 
Button.  It  has  a  3-D  appearance  and  seems  to  be  depressed  when  clicked  on.  It  invokes  sep 
arate  callbacks  for  button  up,  button  down,  and  button  click,  much  like  the  equivalent  widg 
ets  in  other  sets. 

The  DrawnButton  works  similarly,  but  allows  the  programmer  to  provide  a  pixmap  for  the 
appearance  of  the  button. 

Figure  A- 14  shows  a  DrawnButton  and  a  PushButton. 


Cancel 


Figure *A- 14.  Motif  DrawnButton  and  PushButton  widgets 

The  CascadeButton  is  similar  in  effect  to  OPEN  LOOK'S  ButtonStack — it  can  have  a  particu 
lar  appearance  that  indicates  that  a  menu  is  invoked,  rather  than  a  single  callback.  Typically, 
this  is  simply  an  arrow  pointing  in  the  direction  where  the  menu  will  appear. 

A  ToggleButton  is  used  for  option  setting,  much  like  OPEN  LOOK'S  RectButton  or  Check- 
Box.  Figure  A- 15  shows  a  box  containing  a  set  of  ToggleButtons. 

The  Separator  widget  can  be  used  to  draw  a  line  or  other  separator  between  a  group  of  widg 
ets  in  a  menu  or  other  box.  It  is  typically  used  in  menus. 

The  List  widget  displays  a  list  of  strings  set  by  the  application,  and  allows  the  user  to  select 
one  or  more  of  the  strings.  The  selected  data  is  passed  to  a  callback  function.  (We'll  talk 
more  about  this  widget  in  the  section  on  scrolling.) 
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A. 2.1 .2    Analog  Controls 

Motifs  Scale  widget  is  similar  to  AT&T's  Slider,  but  more  powerful,  since  it  can  be  used  to 
display  as  well  as  to  control  analog  values. 

A.2.2   Composite  Widgets 

As  with  OPEN  LOOK,  we've  divided  the  discussion  of  Composite  widgets  into  three  areas, 
Menus  and  Control  Areas,  General-Purpose  Composite  Widgets,  and  Scrollable  Windows. 
These  distinctions  are  somewhat  arbitrary,  and  in  the  case  of  menus,  the  sections  overlap  with 
the  one  on  Pop  ups,  which  appears  later. 

A.2.2. 1    Menus  and  Control  Areas 

Motif  provides  a  special  Shell  widget  class  called  MenuShell  for  managing  pop-up  menus. 
However,  most  actual  menu  displays  are  managed  by  the  RowColumn  composite  widget, 
which,  like  OPEN  LOOK'S  ControlArea,  displays  buttons  in  rows  or  columns. 

Through  resources,  the  RowColumn  widget  can  be  configured  to  create  such  specialized, 
predefined  elements  as  a  MenuBar  (which  can  only  accept  CascadeButton  widgets  as  chil 
dren),  several  different  styles  of  pull-down  or  pop-up  menu  panes,  and  several  preconfigured 
control  areas,  such  as  a  "Radio  Box"  containing  multiple  exclusive  ToggleButton  gadgets. 

Here  you  can  begin  to  see  the  wide  divergence  in  programming  style  made  possible  by  the  Xt 
Intrinsics.  It  is  possible  to  create  a  hierarchy  of  relatively  simple  widgets  to  perform  separate 
parts  of  a  task,  or  a  single,  very  complex  widget  which  is  highly  configurable.  In  one  of  its 
incarnations,  the  RowColumn  widget  is  equivalent  to  an  OPEN  LOOK  ControlArea  plus  an 
Exclusives  widget;  in  another,  a  ControlArea  plus  a  Nonexclusives. 

In  general,  Motif  widgets  are  more  complex,  and  have  many  more  resources,  than  widgets 
provided  in  other  widget  sets.  To  simplify  their  use,  though,  Motif  provides  numerous  conve 
nience  functions.  For  example,  XmCreateRadioBox  will  create  a  RowColumn  widget 
with  one  specialized  set  of  resources,  while  XmCreateMenuBar  will  create  one  that  is 
entirely  different  in  appearance  and  function. 

Figure  A- 15  shows  a  RowColumn  widget  configured  as  a  MenuBar  and  Figure  A- 16  shows 
one  configured  as  a  RadioBox  (each  with  appropriate  children). 


418  X  Toolkit  Intrinsics  Programming  Manual 


menu 
bar 


File 


Edit 


View 


Options 


Help  (Fl) 


Figure  A-15.  A  Motif  RowColumn  widget  configured  as  a  Menu  Bar 


\ 
/ 

^1                                        Font  Selection                                  j  1  Jjl 

j 

Italics                     Weight                Family                       Point  Size 

\S  Don't  care         >/  Don't  care      ^  Don't  care            >y  10  point 
^  Normal              ^  Normal           ^  Times                    ^  12  point 
^  Oblique             ^  Bold              >,,/  Helvetica             ^  14  point 
^Italic                 N/r  Eterni             N/rAvant  Garde         v  18  point 

>,  Reverse             xx  Book 
Italic 

-76.  >4  Motif  RowColumn  widget  configured  with  four  Radio  Boxes 


Appendix  A:  OPEN  LOOK  and  Motif 


419 


Figure  A- 17  shows  a  RowColumn  widget  implementing  a  drop-down  menu. 
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Figure  A-17.  A  Motif  RowColumn  widget  configured  as  a  drop-down  menu 

Items  on  Motif  menus  can  be  selected  by  dragging  the  pointer  down  the  menu  and  releasing 
it  when  the  chosen  item  is  highlighted.  Alternately,  the  pointer  can  simply  be  clicked  on  the 
menu  title  to  drop  down  the  menu.  Clicking  on  an  item  in  the  menu  selects  it;  clicking  any 
where  other  than  in  the  menu  pops  the  menu  down  without  executing  any  item. 

Note  also  that  as  a  general  feature,  Motif  menus  support  accelerators.  That  is,  there  are  key 
board  equivalents  for  every  menu  item.  These  keyboard  accelerators  are  listed  after  the 
menu  label,  as  shown  above.  In  addition,  typing  the  underlined  letter  in  any  menu  item  label 
when  the  pointer  is  in  the  menu  will  select  that  menu  item.  These  are  called  "mnemonics." 

The  items  on  a  menu  bar  or  menu  pane  simply  appear  as  labels,  but  when  selected,  take  on 
the  3-D  appearance  of  a  PushButton. 
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.2.2.2    General  Purpose  Composite  Widgets 

The  BulletinBoard  widget  provides  simple  composite  management,  allowing  widgets  to  be 
placed  arbitrarily  anywhere  within  its  confines.  The  only  constraint  is  that  they  are  not 
allowed  to  overlap. 

The  Form  widget  is  a  subclass  of  BulletinBoard,  that,  like  the  widgets  of  the  same  name  in 
other  sets,  allows  children  to  be  laid  out  relative  to  each  other  or  to  one  or  another  of  the 
sides  of  the  Form.  The  children  will  thus  always  maintain  their  proper  relative  position  when 
the  application  is  resized. 

Figure  A- 18  shows  a  fully  configured  Form. 
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Figure  A-18.  A  Motif  Form  widget  and  children 

The  Frame  widget  is  used  simply  to  provide  a  consistent  border  for  widgets  that  might  not 
otherwise  have  one.  One  use  is  to  give  a  RowColumn  widget  a  border  with  a  3-D  appear 
ance. 
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A.2.2.3    Scrollable  Windows 

A  Motif  ScrollBar  is  illustrated  in  Figure  A- 19. 


A 


Figure  A-19.  A  Motif  ScrollBar 

Like  the  Athena  Scroll  widget,  the  scrollbar  has  a  "thumb"  or  slider  that  can  be  dragged  up 
and  down  to  scroll  the  associated  window.  You  can  also  click  above  or  below  the  thumb  to 
move  it  a  screenful  at  a  time.  Unlike  the  Athena  widget,  it  also  displays  arrows  at  either  end 
that  can  be  used  to  scroll  line  by  line.  The  associated  window  scrolls  in  the  indicated  direc 
tion  as  long  as  the  pointer  button  is  held  down  in  one  of  the  arrows. 

There  are  several  different  types  of  scrolling  windows.  The  ScrolledWindow  widget,  like 
Athena's  Viewport,  provides  a  general  mechanism  for  attaching  scrollbars  to  some  other  win 
dow. 

The  MainWindow  widget  is  a  subclass  of  ScrolledWindow  with  a  special  appearance 
reserved  for  application  main  windows.  Figure  A- 14  showed  a  MainWindow  widget 

Using  the  XmCreateScrolledList  function,  a  List  widget  can  be  created  as  a  child  of 
a  ScrolledWindow,  giving  the  effect  of  a  simple  scrolled  list.  In  addition,  there  are  several 
flavors  of  more  complex  scrolling  lists.  These  include  the  SelectionBox  widget,  and  its  two 
subclasses,  Command  and  FileS  election  Box. 

A  general-purpose  SelectionBox  is  akin  to  a  ScrolledWindow/List  combination,  but  adds  a 
Text  widget  for  entering  additional  data  not  on  the  list,  and  at  least  three  buttons,  labeled  by 
default  OK,  Cancel  and  Help. 
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Figure  A-20  shows  a  SelectionBox. 
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Figure  A-20.  A  Motif  SelectionBox 
/ 

A  FileSelectionBox  is  a  SelectionBox  specially  designed  to  present  a  list  of  filenames  for 
selections.  A  Command  widget  is  a  special  kind  of  SelectionBox  whose  list  consists  of  the 
history  of  commands  entered  in  the  Text  widget  Each  time  a  new  command  is  entered,  it  is 
added  to  the  history  list. 


A.2.3    Pop  Dps 


Motif  defines  two  classes  of  Shell  widgets:  DialogShell,  which  is  used  for  parenting  Dialog 
boxes,  and  MenuShell,  which  is  used  for  menus.  These  classes  are  rarely  instantiated 
directly,  but  are  instead  created  by  convenience  functions  that  also  create  their  composite 
children. 

For  example,  functions  exist  to  create  a  DialogShell  with  a  variety  of  pre-configured 
MessageBox  widgets  as  the  visible  child. 
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As  we've  already  discussed,  a  specially  configured  RowColumn  widget  is  used  to  create  a 
menu  pane  as  the  visible  child  of  a  MenuShell  widget. 

A.2.4  Text  Widgets 

Like  Athena  and  the  AT&T  OPEN  LOOK  widgets,  Motif  provides  a  Text  widget  that  supports 
a  complete  editing  command  set  Like  Athena,  and  unlike  AT&T's  OPEN  LOOK  widget  set, 
both  single-  and  multiline  editing  is  supported  by  a  single  widget 

A.2.5   Drawing  Areas 

As  you  may  recall,  to  do  drawing  in  the  Athena  widgets,  we  either  created  a  custom  widget, 
or  instantiated  a  Core  widget  in  order  to  obtain  a  window  for  drawing.  The  Motif  Drawing- 
Area  widget  class  answers  this  need  in  Motif.  It  provides  a  window  for  drawing,  and  very 
simple,  bulletin-board  like  composite  management  of  children. 

Though  the  name  of  this  widget  class  sounds  promising,  you  should  be  aware  that  Motif 
really  provides  no  more  sophisticated  drawing  capabilities  than  Athena  or  the  AT&T  OPEN 
LOOK  widget  set  In  each  case,  once  you  have  selected  the  widget  to  draw  on,  you  simply 
draw  in  its  window  using  Xlib  calls. 
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The  Varargs  Interfaces 


This  appendix  describes  the  WidgetWrap  and  R4  libraries  that  allow  you  to 
replace  argument  lists  with  resource  settings  placed  directly  in  the  calls  that 
require  them. 


In  This  Appendix: 
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As  noted  in  Chapter  3,  Other  Widget  Programming  Techniques,  there  are  two  varargs 
libraries,  one  called  WidgetWrap,  written  independently  of  MIT  and  available  in  R3  in  the 
directory  contriblwidgetslwidgetwrap ,  and  one  that  is  part  of  the  Xt  standard  but  only  avail 
able  starting  in  R4.  This  appendix  describes  both  of  these  libraries.  The  description  of  the 
R4  interface  is  preliminary,  since  the  specification  is  now  under  public  review  and  may 
change  slightly  before  Release  4. 


B.1   The  R4  Varargs  Interface 


All  Xt  interfaces  that  require  ArgList  arguments  have  analogs  that  conform  to  the  ANSI  C 
variable-length  argument-list  calling  convention.  The  name  of  the  analog  is  formed  by 
inserting  Va  in  the  name  of  the  corresponding  procedure  that  takes  an  ArgList  argument; 
e.g.,  xtVaCreateWidget  is  the  varargs  version  of  xtCreateWidget.  Each  proce 
dure  named  XtVa*  takes  as  its  last  arguments,  in  place  of  the  corresponding  Arg- 
List/Cardinal  parameters,  a  variable-length  parameter  list  of  resource  name  and  value 
pairs  where  each  name  is  of  type  String  and  each  value  is  of  type  Xt  ArgVal.  The  end  of 
the  list  is  identified  by  a  name  entry  containing  NULL.  The  ArgList  and  varargs  forms  of 
the  calls  can  be  used  interchangeably. 

Table  B-l  presents  all  the  varargs  calls  and  their  xtArgVal  equivalents. 
Table  B- 1.  Varargs  Calls  and  XtArg  Val  Equivalents 


Varargs  Version 


XtVaCreateWidget 

XtVaAppCreateShell 

XtVaAppInitialize 

XtVaCreateManagedWidget 

XtVaCreatePopupShell 

XtVaCreatePopupShell 

XtVaGetSubresources 

XtVaGetApplicationResources 

XtVaGetValues 


XtArgVal  Version 


XtCreateWidget 

XtAppCreateShell 

XtApp Initialize 

XtCreateManagedWidget 

XtCreatePopupShell 

XtCreatePopupShell 

XtGetSubresources 

XtGetApplicationResources 

XtGetValues 
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Table  B-1.  Varargs  Calls  and XtArgVal Equivalents  (continued) 


Varargs  Version 


XtVaGetSubvalues 

XtVaSetValues 

XtVaSetSubvalues 


XtArgVal  Version 


XtGetSubvalues 
XtSetValues 
Xt Set Subva lues 


B.1.1    XtVaTypedArg  and  XtVaNestedList 

Two  special  names  are  defined  for  use  only  in  varargs  lists;  XtVaTypedArg  and  Xt 
VaNestedList.  If  the  name  XtVaTypedArg  is  specified  in  place  of  a  resource  name, 
then  the  four  arguments  immediately  following  are  interpreted  as  a  name,  type,  value,  and 
size,  where  name  is  of  type  String,  type  is  of  type  String,  value  is  of  type  XtArgVal, 
and  size  is  of  type  int.  When  a  varargs  list  containing  XtVaTypedArg  is  processed,  a 
resource  type  conversion  is  performed,  if  necessary,  to  convert  the  value  into  the  format 
required  by  the  associated  resource.  If  the  type  is  xtRString,  then  the  value  contains  a 
pointer  to  the  string  and  the  size  contains  the  number  of  bytes  allocated,  including  the  trailing 
NULL  byte.  If  the  type  is  not  xtRString,  then  if  the  size  is  less  than  or  equal  to 
sizeof  (XtArgVal) ,  the  value  should  be  the  data  cast  to  the  type  XtArgVal;  otherwise 
the  value  is  a  pointer  to  the  data.  If  the  type  conversion  fails,  for  any  reason,  a  warning  mes 
sage  is  issued  and  the  list  entry  is  skipped. 

If  the  name  XtVaNestedList  is  specified  in  place  of  a  resource  name,  then  the  argument 
immediately  following  is  interpreted  as  a  pointer  to  another  varargs  list  that  is  logically 
inserted  into  the  original  list  at  the  point  of  declaration.  The  end  of  the  nested  list  is  identi 
fied  with  a  name  entry  containing  NULL.  Varargs  lists  may  nest  to  any  depth. 

xtVaCreateArgsList  dynamically  allocates  a  varargs  list  for  use  with  Xt 
VaNestedList  in  multiple  calls. 

SYNOPSIS 

typedef  XtPointer  XtVarArgsList; 
XtVarArgsList  XtVaCreateArgsList (unused,  . . . ) 

ARGUMENTS 

unused  This  argument  is  not  currently  used  and  must  be  specified  as  NULL. 

.  .  .  Specifies  a  variable-length  parameter  list  of  resource  name  and  value 

pairs. 
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DESCRIPTION 

XtVaCreateArgsList  allocates  memory  and  copies  its  arguments  into  a  single  list 
pointer  which  may  be  used  with  xtVaNestedList.  The  end  of  both  lists  is  identified 
by  a  name  entry  containing  NULL.  The  list  may  be  freed  using  xtFree  when  no  longer 
needed. 

Note  that  XtVaTypedArg  is  not  supported  for  XtVaSetSubvalues. 


B.2  WidgetWrap 

The  WidgetWrap  library  was  written  by  Dan  Heller,  who  can  be  reached  at 
<island!argv@sun.com>  or  <dheller@ucbcory.berkeley.edu>.  What  follows  is  the  summary 
documentation  written  by  Dan  in  the  WidgetWrap  source  file: 

WidgetWrap  provides  four  interfaces: 

WidgetCreate (name,  class,  parent,  varargs...); 
WidgetSet (name,  varargs); 
WidgetGet (name,  varargs) ; 
GenericWidgetName (buf ) ; 

The  purpose  of  this  module  is  to  allow  the  programmer  to  create  widgets  and  set/get  widget 
attributes  via  a  variable  argument  list  style  of  function  call.  This  eliminates  the  need  for 
many  local  variables  and  bothersome  xt  Set  Arg  ( )  calls.  An  example  of  usage: 

Widget    foo; 

J  foo  =  WidgetCreate ("foo",  labelWidgetClass,  toplevel, 
XtNlabel,  "Widget", 

XtNforeground,  WhitePixelOf Screen (XtScreen (toplevel)  )  , 
XtNbackground,  BlackPixelOfScreen (XtScreen (toplevel) )  , 
XtNborderWidth,     1, 
NULL) ; 

As  you  can  see,  the  list  must  be  NULL  terminated.  You  may  pass  up  to  MAXARGS  argument 
pairs.  Increase  this  number  in  WidgetWrap. h,  if  necessary. 

Special  args  are  available  to  the  WidgetCreate,  WidgetSet,  and  WidgetGet  func 
tions: 


Resource  Names 


XtNmanaged 
XtNargList 
XtNpopupShell 
XtNapplicShell 


Decription 


Pass  FALSE  to  create  a  non-managed  widget 
Takes  two  parameters. 
Pass  TRUE  to  create  a  PopupShellWidget. 
Pass  TRUE  to  create  an  applicationShellWidget. 


The  XtNargList  makes  it  possible  to  pass  attributes  to  the  WidgetCreate,  Widget- 
Set,  and  WidgetGet  calls  that  are  probably  common  to  many  widgets  to  be  created  or 
reset. 
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static  Arg  args [ ]  =  { 

XtNforeground,    black, 

XtNbackground,    white, 

XtNwidth,  20, 

XtNheight,   10, 
>; 
foo  =  WidgetCreate ("bar",  widgetClass,  toplevel, 

XtNargList,  args,  XtNumber (args) ,  NULL); 

Most  large  applications  will  create  huge  numbers  of  widgets,  and  the  programmer  has  to 
think  up  unique  names  for  all  of  them.  What's  more,  typically,  as  noted  by  the  examples 

above,  the  names  are  constant  strings  which  take  up  memory,  disk  spaces,  etc So,  if 

WidgetCreate  ()  gets  NULL  as  the  name  of  the  widget,  then  a  widget  name  will  be 
created  automatically.  Since  most  of  the  time,  users  don't  care  what  the  name  of  a  widget  is, 
this  capability  is  available. 

Finally,  note  that  there  are  many  different  implementations  of  varargs.  To  maintain  portabil 
ity,  it  is  important  to  never  return  from  a  function  that  uses  varargs  without  calling 
va_end().  va_start()  and  va_end()  should  always  exist  in  the  same  block  of 
{ }  's.  There  can  be  blocks  between  them,  but  va_end  ( )  shouldn't  be  in  a  block  inside  of 
the  va_start  ()  stuff.  This  is  to  allow  support  for  weird  implementations  which  define 
va_start  ( )  to  something  like:  "  —  {  "  (Pyramid  computers,  for  one).  Also,  if  you  use 
varargs,  never  declare  "known"  arguments;  extract  them  from  the  vararg  list  later. 
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Specifying  Fonts  and  Colors 


This  appendix  describes  the  possible  values  for  color,  font,  and  geometry 
resource  specifications. 
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This  appendix  describes  the  possible  values  for  color,  font,  and  geometry  resource  specifica 
tions. 


C.1   Color  Specification 

Many  clients  have  resources  and  command-line  options  that  allow  you  to  specify  the  color  of 
the  window  background,  foreground  (the  color  that  text  or  graphic  elements  will  be  drawn 
in),  or  window  border.  For  example,  the  following  resources  might  be  set  for  a  Label  widget: 

.       *background:         orange  set  the  background  color  to  orange 

*  foreground:        black  set  the  foreground  color  to  black 

*borderColor  :      black  This  must  be  Halloween! 

The  corresponding  command-line  options  have  the  form: 
-bg  col  or          sets  the  background  color 
-fg  col  or          sets  the  foreground  color 
-bd  col  or          sets  the  border  color 

Some  clients  allow  additional  options  to  specify  color  for  other  elements,  such  as  the  cursor, 
highlighting,  and  so  on. 

By  default,  the  background  is  usually  white  and  the  foreground  black,  even  on  color  worksta 
tions.  You  can  specify  a  new  color  using  either  the  names  in  the  X  Window  System's  color 
name  database  or  hexadecimal  values. 


C.1.1    Color  Names 

The  rgb.txt  file,  usually  located  in  lusrlliblXll  on  UNIX  systems,  is  supplied  with  X  and  con 
sists  of  predefined  colors  assigned  to  specific  (but  not  necessarily  intuitive)  names.* 

*A  corresponding  compiled  file  called  rgb.pag  contains  the  definitions  used  by  the  server,  the  rgb.M  file  is  the  hu 
man-readable  equivalent 
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The  following  are  the  default  color  names  that  come  with  the  X  Window  System.  (See 
Appendix  A,  System  Management,  in  Volume  Three,  X  Window  System  User's  Guide,  for 
information  on  customizing  color  name  definitions.)  This  file  is  not  part  of  the  X  standard,  so 
vendors  are  free  to  modify  it  However,  most  will  just  add  to  it,  or  redefine  the  values  associ 
ated  with  each  color  name  for  better  effects  on  their  display  hardware. 


aquamarine 

cadet blue 

lightsteelblue 

navyblue 

steelblue 

gold 

darkgreen 

mediumforestgreen 

seagreen 

darks lategray 

lightgray 

orange 

pink 

mediumvioletred 

sienna 

darkturquoise 

wheat 


mediumaquamarine 

cornf lowerblue 

mediumblue 

navy 

coral 

goldenrod 

darkol i vegreen 

mediumseagreen 

springgreen 

dimgrey 

khaki 

orchid 

plum 

orangered 

tan 

med i umt urquoi se 

white 


black 

darks lateblue 

mediumslateblue 

skyblue 

cyan 

mediumgoldcnrod 

forestgreen 

mediumspringgreen 

yellowgreen 

dimgray 

magenta 

darkorchid 

red 

violetred 

thistle 

violet 

yellow 


blue 

lightblue 

midnightblue 

slateblue 

firebrick 

green 

limegreen 

palegreen 

darks lategrey 

lightgrey 

maroon 

med iumor chid 

indianred 

salmon 

turquoise 

blueviolet 

greenyellow 


These  names  can  be  used  directly  when  the  specific  color  is  wanted. 
For  example,  the  command  line: 

%  xterro  -bg  lightblu*  -f  g  darkslategray  -bd  plum  & 

creates  an  xterm  window  with  a  background  of  light  blue,  foreground  of  dark  slate  gray,  and 
border  of  plum.  Note  that  the  RGB  values  in  the  color  database  provided  by  MIT  are  correct 
for  only  one  type  of  display;  you  may  find  that  the  color  you  get  is  not  exactly  what  you 
expect  given  the  name.  Vendors  may  have  corrected  the  RGB  values  to  give  colors  closer  to 
what  the  name  implies. 

At  the  command  line,  a  color  name  should  be  typed  as  a  single  word  (for  example,  dark- 
s lategray).  However,  you  can  type  the  words  comprising  a  color  name  separately  if  you 
enclose  them  in  quotes,  as  in  the  following  command  line: 

%  xtezm  -bg  "light  blue"   -fg   "dark   slata  gray"   -bd  plum  & 


C.1.2   Hexadecimal  Color  Specification 

You  can  also  specify  colors  more  exactly  using  a  hexadecimal  color  string.  You  probably 
won't  use  this  method  unless  you  require  a  color  not  available  by  using  a  color  name.  More 
over,  you  shouldn't  use  this  method  unless  necessary  because  it  tends  to  discourage  the  shar 
ing  of  colors  between  applications.  In  order  to  understand  how  this  works,  you  may  need  a 
little  background  on  how  color  is  implemented  on  most  workstations. 


434 


X  Toolkit  Intrinsics  Programming  Manual 


C.1 .2.1    The  RGB  Color  Model 

Most  color  displays  on  the  market  today  are  based  on  the  RGB  color  model.  Each  pixel  on 
the  screen  is  actually  made  up  of  three  phosphors:  one  red,  one  green,  and  one  blue.  Each  of 
these  three  phosphors  is  excited  by  a  separate  electron  beam.  When  all  three  phosphors  are 
fully  illuminated,  the  pixel  appears  white  to  the  human  eye.  When  all  three  are  dark,  the 
pixel  appears  black.  When  the  illumination  of  each  primary  color  varies,  the  three  phosphors 
generate  a  subtractive  color.  For  example,  equal  portions  of  red  and  green,  with  no  admix 
ture  of  blue,  makes  yellow. 

As  you  might  guess,  the  intensity  of  each  primary  color  is  controlled  by  a  three-part  digital 
value — and  it  is  the  exact  makeup  of  this  value  that  the  hexadecimal  specification  allows  you 
to  set 

Depending  on  the  underlying  hardware,  different  servers  may  use  a  larger  or  smaller  number 
of  bits  (from  4  to  16  bits)  to  describe  the  intensity  of  each  primary.  To  insulate  you  from  this 
variation,  clients  are  designed  to  take  color  values  containing  anywhere  from  4  to  16  bits  (1 
to  4  hex  digits),  and  the  server  then  scales  them  to  the  hardware.  As  a  result,  you  can  specify 
hexadecimal  values  in  any  one  of  the  following  formats: 

#RGB 
tRRGGBB 
#RRRGGGBBB 
#RRRRGGGGBBBB 

where  R,  G,  and  B  represent  single  hexadecimal  digits  and  determine  the  intensity  of  the  red, 
green,  and  blue  primaries  that  make  up  each  color. 

When  fewer  than  four  digits  are  used,  they  represent  the  most  significant  bits  of  the  value. 
For  example,  #3a6  is  the  same  as  #3000a0006000. 

What  this  means  concretely  is  perhaps  best  illustrated  by  looking  at  the  values  that  corre 
spond  to  some  colors  in  the  color  name  database.  We'll  use  8-bit  values  (two  hexadecimal 
digits  for  each  primary)  because  that  is  the  way  they  are  defined  in  the  rgb.txt  file: 

#000000  black 

tFCFCFC  white 

#FFOOOO  red 

tOOFFOO  green 

tOOOOFF  blue 

#FFFFOO  yellow 

#OOFFFF  cyan 

tFFOOFF  magenta 

#5F9F9F  cadet  blue 

#42426F  cornflower  blue 

#BFD8D8  light  blue 

#8F8FBC  light  steel  blue 

#3232CC  medium  blue 

I23238E  navy  blue 

t3299CC  sky  blue 

#007FFF  slate  blue 

#236B8E  steel  blue 
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As  you  can  see  from  the  colors  given  above,  pure  red,  green,  and  blue  result  from  the  corre 
sponding  bits  being  turned  full  on.  All  primaries  off  yields  black,  while  all  nearly  full  on 
gives  white.  Yellow,  cyan,  and  magenta  can  be  created  by  pairing  two  of  the  other  primaries 
at  full  intensity.  The  various  shades  of  blue  shown  above  are  created  by  varying  the  intensity 
of  each  primary — sometimes  in  unexpected  ways. 

The  bottom  line  here  is  that  if  you  don't  intimately  know  the  physics  of  color,  the  best  you 
can  do  is  to  look  up  existing  colors  from  the  color  name  database  and  experiment  with  them 
by  varying  one  or  more  of  the  primaries  till  you  find  a  color  you  like.  Unless  you  need  pre 
cise  colors,  you  are  probably  better  off  using  color  names. 

In  any  event,  using  hexadecimal  values  for  colors  is  not  generally  recommended,  since  it  dis 
courages  sharing  of  color  cells. 

C.1 .2.2    How  Many  Colors  are  Available? 

The  number  of  distinct  colors  available  on  the  screen  at  any  one  time  depends  on  the  amount 
of  memory  available  for  color  specification. 

A  color  display  uses  multiple  bits  per  pixel  (also  referred  to  as  multiple  planes  or  the  depth  of 
the  display)  to  select  colors.  Programs  that  draw  in  color  use  the  value  of  these  bits  as  a 
pointer  to  a  lookup  table  called  a  colormap,  in  which  each  entry  (or  color  cell)  contains  the 
RGB  values  for  a  particular  color.*  As  shown  in  Figure  C-l,  any  given  pixel  value  is  used  as 
an  index  into  this  table — for  example,  a  pixel  value  of  16  will  select  the  sixteenth  colorcell. 


"'There  is  a  type  of  high-performance  display  in  which  pixel  values  are  used  directly  to  control  the  illumination  of  the 
red,  green,  and  blue  phosphors,  but  far  more  commonly,  the  bits  per  pixel  are  used  indirectly,  with  the  actual  color 
values  specified  independently,  as  described  here. 
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Frame 
Buffer 


Colormap 

RGB 


Figure  C-1.  Multiple  planes  used  to  index  a  colormap 

This  implementation  explains  several  issues  that  you  might  encounter  in  working  with  color 
displays. 

First,  the  range  of  colors  possible  on  the  display  is  a  function  of  the  number  of  bits  available 
in  the  colormap  for  RGB  specification.  If  8  bits  are  available  for  each  primary,  then  the 
range  of  possible  colors  is  256  3  (somewhere  over  16  million  colors).  This  means  that  you 
can  create  incredibly  precise  differences  between  colors. 

However,  the  number  of  different  colors  that  can  be  displayed  on  the  screen  at  any  one  time 
is  a  function  of  the  number  of  planes.  A  four-plane  system  can  index  24  colorcells  (16  dis 
tinct  colors);  an  eight-plane  system  can  index  28  colorcells  (256  distinct  colors);  and  a 
24-plane  system  can  index  2  u  colorcells  (over  16  million  distinct  colors). 

If  you  are  using  a  four-plane  workstation,  the  fact  that  you  can  precisely  define  hundreds  of 
different  shades  of  blue  is  far  less  significant  than  the  fact  that  you  can't  use  them  all  at  the 
same  time.  There  isn't  space  for  all  of  them  to  be  stored  in  the  colormap  at  one  time. 

This  limitation  is  made  more  significant  by  the  fact  that  X  is  a  multiclient  environment. 
When  X  starts  up,  usually  no  colors  are  loaded  into  the  colormap.  As  clients  are  invoked, 
certain  of  these  cells  are  allocated.  But  when  all  of  the  free  colorcells  are  used  up,  it  is  no 
longer  possible  to  request  new  colors.  When  this  happens,  you  will  usually  be  given  the 
closest  possible  color  from  those  that  have  already  been  allocated.  However,  you  may 
instead  be  given  an  error  message  and  told  that  there  are  no  free  colorcells. 

In  order  to  minimize  the  chance  of  running  out  of  colorcells,  many  programs  use  "shared" 
colorcells.  Shared  colorcells  can  be  used  by  any  number  of  applications,  but  they  can't  be 
changed  by  any  of  them.  They  can  be  deallocated  only  by  each  application  that  uses  them, 
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and  when  all  applications  have  deallocated  the  cell,  it  is  available  for  setting  one  again. 
Shared  cells  are  most  often  used  for  background,  border,  and  cursor  colors. 

Alternately,  some  clients  have  to  be  able  to  change  the  color  of  graphics  they  have  already 
drawn.  This  requires  another  kind  of  cell,  called  private,  which  can't  be  shared.  A  typical 
use  of  a  private  cell  would  be  for  the  pallette  of  a  color  mixing  application.  Such  a  program 
might  have  three  bars  of  each  primary  color,  and  a  box  which  shows  the  mixed  color.  The 
primary  bars  would  use  shared  cells,  while  the  mixed  color  box  would  use  a  private  cell. 

In  summary,  some  programs  define  colorcells  to  be  read-only  and  shareable,  while  others 
define  colorcells  to  be  read/write  and  private. 

To  top  it  off,  there  are  even  clients  that  may  temporarily  swap  in  a  whole  private  colormap  of 
their  own.  Because  of  the  way  color  is  implemented,  if  this  happens,  all  other  applications 
will  be  displayed  in  unexpected  colors. 

In  order  to  minimize  such  conflicts,  you  should  request  precise  colors  only  when  necessary. 
By  preference,  use  color  names  or  hexadecimal  specifications  that  you  specified  for  other 
applications. 

For  more  information  on  color,  see  Chapter  7,  Color,  in  Volume  One,  Xlib  Programming 
Manual. 


C.2  Font  Specification 

Most  widgets  that  display  text  allow  you  to  specify  the  font  to  be  used  in  displaying  text  in 
the  widget,  via  either  the  xtNf  ont  resource,  or  the  -fn  and  -font  command  line  options. 

The  X  Window  System  supports  many  different  display  fonts,  with  different  sizes  and  type 
styles.  (These  are  screen  fonts  and  are  not  to  be  confused  with  printer  fonts.) 

In  Release  2,  not  many  of  the  fonts  were  very  good.  In  Release  3,  Adobe  Systems,  Inc.,  and 
Digital  Equipment  Corporation  jointly  contributed  five  families  of  screen  fonts  (Courier,  Hel 
vetica,  New  Century  Schoolbook,  Symbol  and  Times)  in  a  variety  of  sizes,  styles,  and 
weights  for  75  dots  per  inch  monitors.  Bitstream,  Inc.,  contributed  its  Charter  font  family  in 
the  same  sizes,  styles,  and  weights  for  both  75  and  100  dots  per  inch  monitors. 

Most  Release  2  fonts  have  been  moved  to  the  user-contributed  distribution 
(lusrIXl  1  r3lcontriblfonts). 

In  Release  3  and  later,  fonts  are  stored  in  three  directories: 


Directory 


lusrlliblXlllfontslmisc 

lusrlliblXlllfontsl75dpi 
lusrlliblXl  1 /fonts/ 100dpi 


Contents 


Six  fixed-width  fonts  (also  available  in  Release  2), 
the  cursor  font 

Fixed-  and  variable- width  fonts,  75  dots  per  inch 
Fixed-  and  variable- width  fonts,  100  dots  per  inch 
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These  three  directories  (in  this  order)  comprise  X's  default  font  path.  The  font  path  can  be 
changed  with  the/p  option  to  the  xset  client,  as  described  in  Volume  Three,  X  Window  Sys 
tem  User's  Guide.  (The  font  path,  together  with  a  great  deal  of  other  information  about  the 
server  defaults,  can  be  listed  with  xset  query.)  All  fonts  in  the  font  path  can  be  listed  with 
xlsfonts,  and  the  characters  in  a  font  can  be  displayed  on  the  screen  with  xfd. 

The  names  of  each  font  file  in  the  font  directories  has  a  filename  extension  of  .snf,  which 
stands  for  server  natural  format.  Fonts  are  distributed  in  binary  distribution  format  (bdf), 
and  may  need  to  be  adapted  for  a  given  server. 


C.2.1    Font  Naming  Conventions 

In  Release  2,  font  names  were  determined  by  the  names  of  the  files  in  which  they  are  stored, 
without  the  .snf  extension.  For  example,  the  Glefg-16.snf  contains  the  font  named  fg-16. 

If  you  do  a  listing  of  any  of  the  Release  3  font  directories,  you'll  notice  that  the  filenames 
also  have  .snf  extensions.  However,  Release  3  font  names  are  not  determined  by  the  names 
of  the  files  in  which  they  are  stored. 

As  of  Release  3,  a  font's  name  is  determined  by  the  contents  of  the  font  property  named 
FONT*  rather  than  the  name  of  the  file  in  which  the  font  is  stored. 

If  you  run  xlsfonts,  you'll  get  an  intimidating  list  of  names  similar  to  the  one  shown  in  Figure 
C-2,  which  upon  closer  examination  contains  a  great  deal  of  useful  information: 


vertical  resolution  in  dpi 


foundry 


weight 


set  width 


points  (in  tenths 
of  a  point) 


average  width  (in 
tenths  of  a  pixel) 


-adobe-courier-bold-o-normal  —  10-100-75-75-m-60-,iso8859-l 


font  family 


slant 


pixels 


spacing       character  set 


horizontal  resolution  in  dpi 


Figure  C-2.  A  Release  3  font  name 


This  rather  verbose  line  is  actually  the  name  of  the  font  stored  in  the  file  courBOlO  (in  the 
75dpi  directory).  This  font  name  specifies  the  foundry  (Adobe),  the  font  family  (Courier), 
weight  (bold),  slant  (Oblique),  set  width  (normal),  size  of  the  font  in  pixels  (10),  size  of  the 


*A  property  is  a  piece  of  information  associated  with  a  window  or  a  font    See  Volume  One,  Xlib  Programming 
Manual,  for  more  information  about  properties. 
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font  in  tenths  of  a  point  (100 — measured  in  tenths  of  a  point,  thus  equals  10  points),  horizon 
tal  resolution  (75dpi),  vertical  resolution  (75dpi),  spacing  (m,  for  monospace),  average  width 
in  tenths  of  a  pixel  (60 — measured  in  tenths  of  a  pixel,  thus  equals  6  pixels)  and  character  set 
(iso8859-l). 

The  meaning  of  many  of  these  statistics  is  obvious.  Some  of  the  less  obvious  information  is 
explained  below. 

Foundry:  The  type  foundry  (in  this  case,  Adobe)  that  digitized  and  supplied  the 

font 

Set  width:  A  value  describing  a  font's  proportionate  width,  according  to  the  foun 

dry.   Typical  set  widths  include:    normal,  condensed,  narrow,  double 
width.  All  of  the  new  Release  3  fonts  have  the  set  width  normal. 

Pixels  and  points:  Type  is  normally  measured  in  points,  a  printer's  unit  equal  to  1/72  of  an 
inch.  The  size  of  a  font  in  pixels  depends  on  the  resolution  of  the  display 
font  in  pixels.  For  example,  if  the  display  font  has  100  dots  per  inch  (dpi) 
resolution,  a  12  point  font  will  have  a  pixel  size  of  17,  while  with  75  dpi 
resolution,  a  12  point  font  will  have  a  pixel  size  of  12. 


Spacing: 


Either  m  (monospace,  i.e.,  fixed- width)  or  p  (proportional,  i.e.,  variable- 
width). 


Horizontal  and  vertical  resolution: 

The  resolution  in  dots  per  inch  that  a  font  is  designed  for.  Horizontal  and 
vertical  figures  are  required  because  a  screen  may  have  different  capaci 
ties  for  horizontal  and  vertical  resolution. 

Average  width:  Mean  width  of  all  characters  in  the  font,  measured  in  tenths  of  a  pixel,  in 
this  case  6  pixels. 

Character  set  ISO,  the  International  Standards  Organization,  has  defined  character  set 
standards  for  various  languages.  The  iso8859-l  in  Figure  C-2  represents 
the  ISO  Latin  1  character  set,  which  is  used  by  all  of  the  Release  3  fonts 
in  the  75dpi  and  100dpi  directories.  The  ISO  Latin  1  character  set  is  a 
superset  of  the  standard  ASCII  character  set,  which  includes  various  spe 
cial  characters  used  in  European  languages  other  than  English.  See 
Appendix  H  of  Volume  Two,  Xlib  Reference  Manual,  for  a  complete  list 
ing  of  the  characters  in  the  ISO  Latin  1  character  set 

This  font  naming  convention  is  intended  to  allow  for  the  unique  naming  of  fonts  of  any  style, 
resolution  and  size.  It  is  powerful,  but  unwieldy. 

To  create  a  label  widget  that  displays  text  in  the  font  stored  in  the  file  courBOlO,  you  could 
use  the  resource  setting: 

* label:       -adobe-courier-bold-o-normal--10-100-75-75-m-60-iso8859-l 

Since  typing  a  font  name  of  this  length  is  neither  desirable  nor  practical,  the  X  Window  Sys 
tem  developers  have  provided  two  alternatives:  wildcarding  and  aliasing. 
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C.2.2   Font  Name  Wildcarding 

Any  unnecessary  part  of  a  font  name  can  be  "wildcarded"  by  specifying  a  question  mark  (?) 
for  any  single  character,  and  an  asterisk  (*)  for  any  group  of  characters. 

For  example,  using  a  wildcarded  font  name,  the  resource  specification  above  could  be  writ 
ten: 

*label:       *courier-bold-o-*-100* 

(Note  that  when  using  wildcards  with  the  -fn  command  line  option,  you  must  take  care  to 
quote  the  font  names,  since  the  UNIX  shell  has  special  meanings  for  the  wildcard  characters  * 
and  ?.  This  can  be  done  by  enclosing  the  entire  font  name  in  quotes,  or  by  escaping  each 
wildcard  character  by  typing  a  backslash  before  it.) 

If  more  than  one  font  in  a  given  directory  matches  a  wildcarded  font  name,  the  server 
chooses  the  font  to  use.  If  fonts  from  more  than  one  directory  match  the  wildcarded  name, 
the  server  will  always  choose  a  font  from  the  directory  that  is  earlier  in  the  font  path.  Thus,  if 
a  wildcarded  font  name  matches  a  font  from  both  the  75dpi  and  100dpi  directories,  and  the 
75dpi  directory  comes  first  in  the  font  path,  the  server  chooses  the  font  from  that  directory. 

In  creating  a  wildcarded  font  name,  you  need  to  decide  which  parts  of  the  standard  font  name 
must  be  explicit  and  which  parts  can  be  replaced  with  wildcards.  As  the  previous  example 
illustrates,  you  can  use  a  single  wildcard  character  for  multiple  parts  of  the  font  name.  For 
instance,  the  final  asterisk  in  the  example  stands  for  the  sequence: 

-75-75-m-60-iso8859-l 

in  the  explicit  font  name.  The  idea  is  to  specify  enough  parts  of  the  font  name  explicitly  so 
that  the  server  gives  you  the  font  you  have  in  mind. 

It's  helpful  to  familiarize  yourself  with  the  available  font  families,  weights,  slants,  and  point 
sizes.  The  following  list  gives  these  statistics  for  the  fonts  in  the  directories  75dpi  and 
100dpi  in  the  standard  X  distribution  from  MIT.*  (The  fonts  in  the  misc  directory  are  hold 
overs  from  Release  2  and  have  short,  manageable  names  that  should  not  require  wildcarding.) 

Font  families:     Charter,  Courier,  Helvetica,  New  Century  Schoolbook,  Symbol,  Times. 

Weights:  medium,  bold. 

Slants:  Roman  (r),  an  upright  design; 

Italic  (i),  an  italic  design  slanted  clockwise  from  vertical; 

Oblique  (o),  an  obliqued  upright  design,  slanted  clockwise  from  vertical. 
Point  sizes:         8, 10, 12, 14, 18, 24. 

If  you're  unfamiliar  with  the  general  appearance  of  a  particular  font  family,  try  displaying 
one  of  the  fonts  with  xfd,  as  described  in  Volume  Three,  X  Window  System  User's  Guide. 


*For  fonts  other  than  those  shipped  by  MIT,  other  families,  weights,  slants,  point  sizes,  etc.,  may  apply. 
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As  a  general  rule,  we  suggest  you  type  the  following  parts  of  a  font  name  explicitly: 

•  Font  family 

•  Weight 

•  Slant 

•  Point  size 

Note  that  it's  better  to  match  the  point  size  field,  which  is  measured  in  tenths  of  a  point  (the 
100  in  the  previous  example,  equal  to  10  points),  than  the  pixel  field  (the  10).  This  allows 
your  wildcarded  font  name  to  work  properly  with  monitors  of  different  resolutions.  For 
example,  say  you  use  the  following  name  to  specify  a  24  point  (size),  medium  (weight),  Italic 
(slant)  Charter  (family)  font: 

*charter-medium-i-*-240-* 

This  will  match  either  of  the  following  two  font  names  (the  first  for  75  dpi  monitors  and  the 
second  for  100  dpi  monitors): 

-bitstream-charter-medium-i-normal--25-240-75-75-p-136-iso8859-l 
-bi tstream-charter-medium-i -normal --33-2 4 0-10 0-1 00-p-136-iso8 85 9-1 

depending  on  which  directory  comes  first  in  your  font  path.  Specifying  font  size  explicitly  in 
pixels  (25  for  the  first  or  33  for  the  second)  rather  than  in  points  would  limit  you  to  matching 
only  one  of  these  fonts. 

Given  the  complexity  of  font  names  and  the  rules  of  precedence  used  by  the  server,  you 
should  use  wildcards  carefully. 

C.2.3   Font  Name  Aliasing 

Another  way  to  abbreviate  font  names  is  by  aliasing — that  is,  by  associating  them  with  alter 
native  names.  You  can  create  a  file  (or  files)  called  fonts. alias,  in  any  directory  in  the  font 
search  path,  to  set  aliases  for  the  fonts  in  that  directory.  The  X  server  uses  bolhfonts.dir  files 
(see  Section  C.2.5)  said  fonts. alias  files  to  locate  fonts  in  the  font  path. 

Be  aware  that  when  you  create  or  edit  afonts.alias  file,  the  server  does  not  automatically 
recognize  the  aliases  in  question.  You  must  make  the  server  aware  of  newly  created  or  edited 
alias  files  by  resetting  the  font  path  with  xset  as  described  in  Section  C.2.4. 

The,  fonts. alias  file  has  a  two-column  format  similar  to  \hefonts.dir  file:  the  first  column  con 
tains  aliases,  the  second  contains  the  actual  font  names.  If  you  want  to  specify  an  alias  that 
contains  spaces,  enclose  the  alias  in  double  quotes.  If  you  want  to  include  double  quotes  or 
other  special  characters  as  part  of  an  alias,  precede  each  special  symbol  with  a  backslash. 

When  you  use  an  alias  to  specify  a  font  in  a  command  line,  the  server  searches  for  the  font 
associated  with  that  alias  in  every  directory  in  the  font  path.  Therefore,  a.  fonts. alias  file  in 
one  directory  can  set  aliases  for  fonts  in  other  directories  as  well.  You  might  choose  to  create 
a  single  alias  file  in  one  directory  bf  the  font  path  to  set  aliases  for  the  most  commonly  used 
fonts  in  all  the  directories.  Example  C-l  shows  a  sample  fonts.alias  file. 
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Example  C-1.  Sample  fonts.alias  file 

xterm!2  -adobe-courier-medium-r-normal — 12-120-75-75-m-70-iso8859-l 
xterm!4  -adobe-courier-medium-r-normal — 14-140-75-75-m-90-iso8859-l 
xtermlS  -adobe-courier-medium-r-normal — 18-180-75-75-m-110-iso8859-l 

As  the  names  of  the  aliases  suggest,  this  sample  file  contains  aliases  for  three  fonts  (of  differ 
ent  point  sizes)  that  are  easily  readable  in  xterm  windows. 

You  can  also  use  wildcards  within  the  font  names  in  the  right  hand  column  of  an  alias  file. 
For  instance,  the  alias  file  above  might  also  be  written: 

xterm!2  *courier-medium-r— *-120* 
xterm!4  *courier-medium-r-*-140* 
xtermlS  *courier-medium-r-*-180* 

Once  the  server  is  made  aware  of  aliases,  you  can  specify  an  alias  in  resource  specifications 
or  on  the  command  line: 

xterm . font :    xterm!2 
or: 

%   xterm  -fn  xterml2 

If  you  are  accustomed  to  the  Release  2  font  naming  convention  (each  font  name  being  equiv 
alent  to  the  name  of  the  file  in  which  it  is  stored,  without  the  .snf  extension),  there  is  a  way  to 
emulate  this  convention  in  Release  3  using  alias  files.  In  each  directory  in  the  font  path,  cre 
ate  a  fonts.alias  file  containing  only  the  following  line: 

FILE_NAMES_ALIASES 

Each  filename  (without  the  .snf  extension)  will  then  serve  as  an  alias  for  the  font  the  file  con 
tains.  Note  that  an  alias  file  containing  this  line  applies  only  to  the  directory  in  which  it  is 
found.  To  make  every  font  name  equivalent  to  the  name  of  the  file  in  which  it  is  stored,  you 
need  to  create  a  fonts.alias  file  such  as  this  in  every  font  directory. 

If  you've  specified  FILE_NAMES_ALIASES  in  an  alias  file,  you  can  choose  the  fonts  in  that 
directory  by  means  of  their  filenames,  as  we  did  in  the  resource  example  at  the  end  of  Chap 
ter  2,  Introduction  to  the  X  Toolkit. 


Making  the  Server  Aware  of  Aliases 

After  you  create  (or  update)  an  alias  file,  the  server  does  not  automatically  recognize  the 
aliases  in  question.  You  must  make  the  server  aware  of  newly  created  or  edited  alias  files  by 
"rehashing"  the  font  path  with  xset.  Enter: 

%   xset  fp  rehash 

on  the  command  line.  The  xset  option.//?  (font  path)  with  the  rehash  argument  causes  the 
server  to  reread  the  fonts. dir  and  fonts. alias  files  in  the  current  font  path.  You  need  to  do  this 
every  time  you  edit  an  alias  file.  (You  also  need  to  use  xset  if  you  add  or  remove  fonts.  See 
Volume  Three,  X  Window  System  User's  Guide,  for  details.) 
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C.2.5   The  fonts.dir  Files 

In  addition  to  font  files,  each  font  dkectory  contains  a  file  called  fonts.dir.  The  fonts.dir  files 
serve,  in  effect,  as  databases  for  the  X  server.  When  the  X  server  searches  the  directories  in 
the  default  font  path,  it  uses  the  fonts. dir  files  to  locate  the  font(s)  it  needs. 

Each  fonts. dir  file  contains  a  list  of  all  the  font  files  in  the  dkectory  with  their  associated  font 
names,  in  two-column  form.  (The  first  column  lists  the  font  file  and  the  second  column  lists 
the  actual  font  name  associated  with  the  file.)  The  first  line  in  fonts.dir  lists  the  number  of 
entries  in  the  file  (i.e.,  the  number  of  fonts  in  the  directory). 

Example  C-2  shows  the  fonts.dir  file  from  the  dkectory  /usr/lib/Xll /fonts/1 00dpi.  As  the 
first  line  indicates,  the  dkectory  contains  24  fonts. 

3*SS 

Example  C-2.  fonts.dir  file  in  /usr/lib/X1 1 /fonts/1 00dpi 

24 

charBIOS.snf  -bitstream-charter-bold-i-normal — 11-80-1 00-100-p-68-iso885 9-1 
charBHO.snf  -bitstream-charter-bold-i-normal — 14-100-100-100-p-86-iso8859-l 
charBI12.snf  -bitstream-charter-bold-i-normal — 17-120-100-1 00-p-105-iso885 9-1 
charBI14.snf  -bitstream-charter-bold-i-normal — 19-140-100-100-p-117-iso8859-l 
charBHS.snf  -bitstream-charter-bold-i-normal — 25-180-100-100-p-154-iso8859-l 

II   charB!24 . snf  -bitstream-charter-bold-i-normal — 33-240-100-100-p-203-iso8859-l 
charBOS.snf   -bitstream-charter-bold-r-normal — ll-80-100-100-p-69-iso8859-l 
charBlO.snf   -bitstream-charter-bold-r-normal — 14-100-100-100-p-88-iso8859-l 
charB!2.snf   -bitstream-charter-bold-r-normal — 17-120-100-100-p-107-iso8859-l 

II   charB14.snf   -bitstream-charter-bold-r-normal — 19-140-100-100-p-119-iso8859-l 
charBlS.snf   -bitstream-charter-bold-r-normal — 25-180-100-100-p-157-iso8859-l 

I!   charB24 . snf   -bitstream-charter-bold-r-normal — 33-240-100-100-p-206-iso8859-l 
charlOS.snf   -bitstream-charter-medium-i -normal — Il-80-100-100-p-60-iso8859-l 
charllO.snf   -bitstream-charter-medium-i-normal — 14-1 00-1 00-1 00-p-76-iso885 9-1 
charI12.snf   -bitstream-charter-medium-i -normal — 17-120-100-100-p-92-iso8859-l 
charI14.snf   -bitstream-charter-medium-i-normal — 19-140-100-100-p-103-iso8859-l 
charllS.snf   -bitstream-charter-medium-i-normal — 25-180-100-100-p-136-iso8859-l 
charI24.snf   -bitstream-charter-medium-i -normal — 33-240-100-100-p-179-iso8859-l 
charROS.snf   -bitstream-charter-medium-r-normal — 11-80-100-1 00-p-61-iso885 9-1 
charRlO.snf   -bitstream-charter-medium-r-normal — 14-100-100-100-p-78-iso8859-l 
charR12.snf   -bitstream-charter-medium-r-normal — 17-120-100-100-p-95-iso8859-l 
charR14.snf   -bitstream-charter-medium-r-normal — 19-140-100-100-p-106-iso8859-l 
charRlS.snf   -bitstream-charter-medium-r-normal — 25-180-100-100-p-139-iso8859-l 
charR24 . snf   -bitstream-charter-medium-r-normal — 33-240-100-100-p-183-iso8859-l 

The  fonts. dir  files  are  created  by  the  mkfontdir  client  when  X  is  installed,  mkfontdir  reads  the 
font  files  in  directories  in  the  font  path,  extracts  the  font  names,  and  creates  a  fonts.dir  file  in 
each  dkectory.  If  fonts. dir  files  are  present  on  your  system,  you  probably  won't  have  to  deal 
with  them,  or  with  mkfontdir,  at  all.  If  the  files  are  not  present,  or  if  you  have  to  load  new 
fonts  or  remove  existing  ones,  you  will  have  to  create  files  with  mkfontdir.  Refer  to  Volume 
Three,  X  Window  System  User's  Guide,  for  details. 
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C.3  Window  Geometry 


All  clients  that  display  in  a  window  take  a  geometry  option  that  specifies  the  size  and  loca 
tion  of  the  client  window.*  The  syntax  of  the  geometry  option  is: 

-geometry   geometry 

The  -geometry  option  can  be  (and  often  is)  abbreviated  to  -g,  unless  there  is  a  conflicting 
option  that  begins  with  g. 

The  corresponding  resource  is  XtNGeometry,  which  can  be  set  in  a  resource  file  as  fol 
lows: 

*mywidget .  geometry :      geometry _str ing 

The  argument  to  the  geometry  option  (geometry),  referred  to  as  a  "standard  geometry 
string,"  has  the  form: 

wi dthxhei gh t±xoff±yoff 

The  variables,  width  and  height,  are  values  in  pixels  for  many  clients.  However,  appli 
cation  developers  are  encouraged  to  use  units  that  are  meaningful  to  the  application.  For 
example,  xterm  uses  columns  and  rows  of  text  as  width  and  height  values  in  the  xterm  win 
dow,  xoff  (x  offset),  and  yoff  (y  offset)  are  always  in  pixels. 

You  can  specify  any  or  all  elements  of  the  geometry  string.  Incomplete  geometry  specifica 
tions  are  compared  to  the  resource  manager  defaults  and  missing  elements  are  supplied  by 
the  values  specified  there.  If  no  default  is  specified  there,  and  uwm  is  running,  the  window 
manager  will  require  you  to  place  the  window  interactively. 

The  values  for  the  jc  and  y  offsets  have  the  following  effects: 
Table  C-1.  Geometry  Specification:  x  andy  Offsets 


Offset  Variables 


Description 


+xoff 
+yoff 
-xoff 
-yoff 


A  positive  x  offset  specifies  the  distance  that  the  left  edge  of  the  win 
dow  is  offset  from  the  left  side  of  the  display. 

A  positive  y  offset  specifies  the  distance  that  the  top  edge  of  the  win 
dow  is  offset  from  the  top  of  the  display. 

A  negative  x  offset  specifies  the  distance  that  the  right  edge  of  the  win 
dow  is  offset  from  the  right  side  of  the  display. 

A  negative  y  offset  specifies  the  distance  that  the  bottom  edge  of  the 
window  is  offset  from  the  bottom  of  the  display. 


*For  compatibility  with  Release  2,  the  alternative  syntax: 

= geometry 
is  still  supported  for  Release  3.  This  syntax  will  not  be  supported  in  future  releases,  however. 
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For  example,  the  command  line: 

%  xclock  -geometry  125x125-10+10  t 

places  a  clock  125x125  pixels  in  the  upper-right  corner  of  the  display,  10  pixels  from  both 
the  top  and  the  right  edge  of  the  screen. 

For  xterm,  the  size  of  the  window  is  measured  in  characters  and  lines.  (80  characters  wide  by 
24  lines  long  is  the  default  terminal  size.)  If  you  wanted  to  use  the  vtlOO  window  in  132-col- 
umn  mode,  with  40  lines  displayed  at  a  time,  you  could  use  the  following  geometry  options: 

%  xterm  -geometry  132x40-10+350  & 

This  will  place  an  xterm  window  132  characters  wide  by  40  lines  long  in  the  lower-right  cor 
ner,  10  pixels  from  the  right  edge  of  the  screen  and  350  pixels  from  the  top  of  the  screen. 

Some  clients  may  allow  you  to  specify  geometry  strings  for  the  size  and  position  of  the  icon 
or  an  alternate  window.  In  Release  2,  this  could  be  done  using  command  line  options.*  As 
of  Release  3,  command  line  options  for  setting  the  geometry  of  an  icon  or  an  alternative  win 
dow  are  supported  only  for  compatibility  with  older  versions  of  X.  (These  options  will  not  be 
supported  in  future  releases.)  However,  several  Release  3  clients,  including  xterm,  allow  you 
to  set  the  size  and  position  of  the  icon  or  alternative  window  using  resource  variables  (in  an 
Xdefaults  or  other  resource  file).  See  the  appropriate  client  reference  pages  in  Part  Three  of 
Volume  Three,  X  Window  System  User's  Guide,  for  a  complete  list  of  available  resources. 

You  should  be  aware  that,  as  with  all  user  preferences,  you  may  not  always  get  exactly  what 
you  ask  for.  Clients  are  designed  to  work  with  a  window  manager,  which  may  have  its  own 
rules  for  window  or  icon  size  and  placement  However,  priority  is  always  given  to  specific 
user  requests,  so  you  won't  often  be  surprised. 


*The  Release  2  version  of  xterm  takes  a  geometry  string  beginning  with  %  rather  than  =  as  the  geometry  for  the  Tek 
tronix  window,  and  one  beginning  with  #  as  the  geometry  for  the  icon.  Neither  of  these  options  requires  a  preceding 
-geometry  or  -g. 
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Naming  Conventions 


777/s  appendix  describes  a  suggested  set  of  conventions  for  naming  widgets, 
and  elements  within  widget  code. 


Naming  Conventions 


This  appendix  proposes  a  set  of  conventions  for  naming  certain  elements  of  widget  code.*  If 
the  naming  conventions  used  in  all  widget  sets  are  consistent,  there  will  be  several  benefits: 

•  It  will  be  much  easier  for  programmers  to  move  from  toolkit  to  toolkit  without  needing  to 
constantly  refer  to  manuals  to  figure  out  how  to  properly  name  various  items. 

•  It  will  be  easier  to  mix  widgets  from  different  widgets  sets  in  one  application. 

•  It  will  make  it  possible  for  automatic  code  generators  to  work  with  lots  of  widgets  with 
out  making  special  modifications  for  any  toolkit. 

These  conventions  are  common  between  the  OPEN  LOOK  and  Motif  widget  sets  with  a  few 
minor  differences.  However,  the  Athena  widget  set  currently  does  not  follow  the  conven 
tions  described. 

It  is  important  to  note  that  these  suggestions  are  in  no  way  blessed  (or  damned)  by  the  X 
Consortium — they  are  simply  a  guideline  that  we  suggest  you  follow  in  the  interests  of  pro 
moting  the  benefits  listed  above.  We  will  use  Motif  as  an  example. 

A  toolkit  uses  a  special  prefix  with  all  its  widgets.  In  the  case  of  Motif,  this  prefix  is  m. 
Using  that  prefix  and  a  hypothetical  Label  widget  as  an  example,  the  conventions  are  as  fol 
lows: 


Toolkit  library  name 
Widget  class  name 
Include  directives 

class_name  field  in 
the  core  structure 

Enumerated  resource  values 
Public  function  names 


libXm.a 
XmLabel 
<Xm/Label.h> 
Label 

XmC  AP I T  AL I Z  ED_WORD  S 
XmLabelFunctionName ( ) 


*This  appendix  is  based  on  a  comp. windows x  netwoik  news  posting  by  Gene  Dykes  of  Cornell  University. 
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Truncated  include  file  names 


Strip  the  lower  case  letters  a  word  at  a  time  until  the 
basename  is  nine  characters  or  fewer  (but  strip  as  few 
letters  as  possible  from  the  initial  word).  Thus: 

<Xm/VeryLongWidgetName . h> 
becomes: 


<Xm/VeryLWN.h> 


but 


Macro  names  for  preprocessor 
in  include  files 


<Xm/Verylongwidgetname . h> 
becomes: 

<Xm/Verylongw . h> 

(Note  difference  in  VeryLong  (two  words)  and  Very- 
long  (one  word).) 

#ifndef  XM_LABEL_H 

This  is  to  prevent  header  files  from  being  included  more 
than  once. 

If  a  widget  has  a  corresponding  gadget,  then  Gadget  is 
appended  to  the  widget  name,  so  XmLabelGadget  is 
the  gadget  class  name. 

xmLabelWidgetClass 
xmLabelGadgetClass 

Widget  XmCreateLabel  (parent,  name, 
arglist,  argcount) 

This  is  a  shortcut  to  using  XtCreateWidget.  How 
ever,  in  the  case  of  top-level  widgets  (menus,  dialogs, 
Main  Window),  it  also  creates  the  shell  widget  and  creates 
the  requested  widget  within  it 

The  special  Create  functions  can  also  be  used  as  conve 
nience  routines  for  specialized  widget  instances.  For 
example,  XmCreateWorkingDialog  and  Xm- 
CreateWarningDialog  actually  create  a  Message- 
Box  whose  XmDialogType  resources  are  respectively 
XmDIALOG_WARNING  and  XmDIALOG_WORKING. 

OPEN  LOOK  uses  conventions  similar  to  Motif,  but  leaves  the  prefixes  off  the  widget  class 
name.  We  recommend  that  you  supply  a  prefix  for  any  widgets  you  write,  especially  if  there 
is  any  chance  that  some  other  widget  set  may  use  the  same  class  name.  In  other  words,  if  we 
wrote  a  new  Label  widget,  we  might  call  it  OraLabcl,  not  just  Label,  so  that  we  could  still  use 
the  Athena  Label  widget  in  the  same  application. 


Widget  class  pointer 
Gadget  class  pointer 

Create  function  for  widgets 
or  gadgets 
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Converting  Widgets  from 
Xll  Release  2  to  Xll  Release  3 


This  appendix  summarizes  the  changes  between  Release  2  and  Release  3  of 
the  X  Toolkit,  as  it  applies  to  converting  widgets  and  applications. 

In  This  Appendix: 

New  Core  Fields 454 

The  Display  Accelerator  Method  454 

The  Extension  Pointer 454 

Obsolete  Composite  Fields 454 

Auditing  Data  Types 455 

Name  Change  to  Misc.h  Header  File 455 

Interface  Change  to  accept_focus  Method  456 

Data  Change  to  set_values  Method  456 

New  Geometry  Request  Mode 456 

Translation  Table  Syntax 457 

Resource  Name  and  Class  Qualifiers 457 

Bug  Fix  to  XtGetValues 458 

Changes  to  Shell  Defaults 458 

XtAddlnput  and  XtAddTimeout 458 


Converting  Widgets  from 
X1 1  Release  2  to  X11  Release  3 


In  the  majority  of  cases,  Xt  applications  correctly  written  for  Release  2  will  be  source  com 
patible  with  the  Release  3  Xt;  however,  some  source  changes  are  necessary  to  widget  imple 
mentations  to  accommodate  the  new  interfaces.  This  document  summarizes  the  changes 
required  to  update  a  widget  that  correctly  functions  under  the  Release  2  library  to  do  the 
same  under  the  Release  3  library.* 

Release  3  of  the  X  Window  System  Version  1 1  includes  the  first  version  of  the  Xt  Intrinsics 
that  have  been  approved  and  adopted  as  part  of  the  core  X  standard  by  the  MIT  X  Consor 
tium.  From  the  viewpoint  of  an  applications  programmer,  the  Release  3  library  is  upward 
compatible  with  the  library  distributed  with  XI 1  Release  2  with  two  small  exceptions,  listed 
in  the  last  four  sections  of  this  document  Of  course,  many  bugs  have  been  fixed  in  the 
Release  3  implementation,  and  it  is  entirely  possible  that  an  application  that  appeared  to 
work  was  actually  leaning  against  such  a  bug  and  will  now  fall  over. 

The  changes  listed  here  are  by  no  means  a  complete  listing  of  all  the  additions  that  have  been 
made  to  the  Intrinsics  in  Release  3.  Only  the  changes  that  require  source  modifications  to 
widgets  and  (possibly)  to  applications  are  described. 

Some  new  core  fields  and  some  small  changes  to  old  methods  will  require  attention  in  the 
source  code  of  any  widgets  written  to  the  Release  2  specification.  The  following  sections 
outline  the  new  core  methods,  some  obsolete  composite  methods,  and  some  changes  to  exist 
ing  methods. 


*This  appendix  is  an  edited  version  of  an  appendix  of  the  Xt  specification  by  Ralph  R.  Swick. 
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E.1   New  Core  Fields 

Two  new  fields  have  been  added  to  the  end  of  the  CoreClassPart  structure  to  allow 
composite  widgets  to  attach  event  translation  bindings  to  their  descendants  and  to  allow  for 
future  updates  to  Co  re  Class.  Revised  Release  2  widgets  can  initialize  both  of  these  new 
fields  to  NULL.  If  the  structure  initialization  followed  the  template  used  by  the  Athena  wid 
gets  in  R2,  the  C  compiler  will  do  this  initialization  automatically  and  source  code  modifica 
tions  are  not  strictly  required. 

E.1.1    The  Display  Accelerator  Method 

Xt  now  supports  input  accelerators.  Accelerators  are  translation  bindings  attached  to  one 
widget  that  invoke  actions  in  a  different  widget,  usually  a  parent 

The  display_accelerator  method  is  called  by  the  XtlnstallAccelerators 
procedure  to  notify  the  widget  owning  the  accelerator  table  (i.e.  the  widget  in  which  the 
actions  will  be  dispatched)  that  its  accelerators  have  been  added  to  the  event  bindings  of 
some  other  target  widget 

Widgets  that  do  not  define  accelerator  tables  should  initialize  the  display_accelera- 
tor  field  to  XtlnheritDisplayAccelerator. 


E.1 .2   The  Extension  Pointer 

In  order  to  allow  for  future  expansion  of  the  CoreClassPart  structure  and  maintain 
binary  compatibility  with  then-existing  widget  libraries,  an  extension  field  has  been  added 
after  the  display_accelerators  field.  This  field  should  be  initialized  to  NULL. 


E.2  Obsolete  Composite  Fields 

Two  methods  have  been  removed  from  the  CompositeClassPart  structure.  Any  wid 
gets  that  are  subclasses  of  Composite  must  be  modified  to  remove  the  initialization  for 
these  two  fields  before  the  widget  can  be  re-compiled. 

The  methods  move_f  ocus_to_next  and  move_f  ocus_to_prev  were  deemed  to  be 
insufficient  for  many  desired  styles  of  focus  management  and  were  therefore  removed.  If  a 
widget  library  desires  to  implement  class  move_f  ocus  methods,  it  should  declare  a  sub 
class  of  Compos iteWidget Class  and  add  the  appropriate  focus  management  methods 
in  the  subclass. 

The  num_mapped_children  field  has  been  removed  from  the  CompositePart  struc 
ture.  This  field  is  no  longer  used  internally  by  the  Intrinsics  and  widgets  that  used  it  them 
selves  were  probably  using  it  incorrectly. 
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A  new  field,  extension,  was  added  to  the  end  of  CompositeClassPart  to  allow  for 
future  growth.  It  should  have  the  value  NULL. 

Note  that  Constraint  is  a  subclass  of  Composite  and  therefore  these  changes  apply  to  all  Con 
straint  widgets. 


E.3  Auditing  Data  Types 

The  data  types  Dimension  and  Position  are  defined  for  the  fields  core. width, 
core. height,  core.border_width,  and  core.x  and  core.y,  respectively. 
Many  other  fields  in  specific  widgets  are  appropriately  defined  as  either  Dimension,  or 
Position.  A  common  programming  error  in  Release  2  was  to  misdeclare  some  or  all  of 
these  fields  as  int,  either  in  a  structure  declaration,  or  more  subtly  in  the  size  field  in  a 
resource  list.* 

In  Release  3,  it  is  critical  that  fields  be  consistently  declared  as  either  int,  Dimension,  or 
Position.  Good  compilers,  lint,  and  other  similar  tools  will  catch  some  programming 
errors  but  cannot  check  resource  lists.  Unpredictable  run-time  errors  will  result  from  fields 
that  have  been  misdeclared. 

In  addition  to  auditing  all  resource  lists,  all  calls  to  xtMakeResizeRequest  in  widgets 
should  be  checked  to  make  sure  the  return  value  pointers  are  of  type  Dimension*  and  all 
uses  of  XtGetValues  in  both  widgets  and  applications  should  be  checked  to  insure  that 
the  pointers  used  in  the  argument  lists  reflect  the  correct  data  type  for  the  resource  being 
retrieved. 


E.4  Name  Change  to  Misc.h  Header  File 

The  header  file  <XlllMisc.h>  exported  by  the  Athena  widgets  has  been  renamed 
<XlllXawMisc.h>.  Any  widgets  or  applications  that  used  it  will  need  to  refer  to  the  new 
name. 


*This  error  was  exacerbated  by  the  Athena  Widget  documentation  and  header  files  which  misdeclared  these  fields  as 
int. 
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E.5  Interface  Change  to  accepMocus  Method 

An  additional  parameter  and  a  return  value  have  been  added  to  the  accept_focus 
method.  The  new  parameter  indicates  the  X  time  of  the  event  that  caused  the  method  to  be 
invoked,  so  that  the  method  can  correctly  conform  to  the  ICCCM.  The  accept_f  ocus 
method  must  also  return  a  Boolean  value  indicating  whether  or  not  the  widget  actually 
wanted  the  keyboard  focus. 


E.6  Data  Change  to  set_values  Method 

It  is  frequently  the  case  that  a  widget  will  need  to  make  some  request  of  its  parent  from 
within  its  set_values  method.  In  Release  2,  the  widget  data  structure  was  not  updated  to 
reflect  the  new  resource  values  until  after  all  class  set_values  methods  had  been  called. 
In  this  case,  the  parent  was  unable  to  perform  any  processing  that  depended  upon  the  new 
state  of  the  child. 

In  Release  3,  the  widget  data  structure  is  updated  with  the  new  resource  values  before  calling 
the  class  set_yalues  methods.  A  copy  is  made  of  the  widget  record  before  the  changes 
are  installed.  The  definition  of  the  arguments  to  the  set_values  method  has  been 
changed  so  that  the  "old"  argument  now  points  to  the  copy  of  the  original  widget  and  the 
"new"  argument  points  to  the  actual  widget  record.  Most  simple  set_values  methods 
will  not  need  any  changes  to  work  properly  with  this  swap,  but  methods  which  made  geome 
try  requests  or  other  changes  that  formerly  required  use  of  the  "old"  widget  must  be  modi 
fied  to  use  the  "new"  argument  instead. 

The  set_yalues  method  must  not  assume  that  the  current  geometry  (i.e.,  the  "new"  one) 
is  the  one  they  will  actually  get,  as  the  parent's  Geometry  Manager  has  not  yet  been  called.  A 
reasonable  strategy  for  widgets  that  need  to  perform  some  set_values  computation  based 
upon  their  geometry  is  to  use  the  old  geometry  and  rely  solely  upon  their  resize  method  to 
notify  them  of  any  changes  after  set_values  has  been  called. 


E.7  New  Geometry  Request  Mode 

In  order  to  accommodate  some  geometry  layout  semantics  that  may  require  a  parent  to 
respond  accurately  with  XtGeometryAlmost  but  simultaneously  propagate  a  geometry 
request  up  the  tree,  a  new  option  has  been  added  to  the  values  permitted  in  the 
request_mode  field  of  an  XtGeometryRequest. 

If  a  Composite  widget  geometry_manager  method  finds  the  xtCWQueryOnly  flag  set 
in  the  request_mode,  it  is  expected  to  respond  to  the  query  in  the  normal  way  but  not  to 
actually  make  any  changes  to  its  own  geometry  or  the  geometry  of  any  of  its  children.  The 
Composite  widget  can  expect  that  the  child  will  repeat  the  request  without  the  xt- 
CWQueryOnly  flag  and  may  cache  any  layout  state  required  to  quickly  re-compute  the  new 
geometry. 
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E.8  Translation  Table  Syntax 

Several  additions  have  been  made  to  the  syntax  permitted  in  translation  tables.  Any  transla 
tion  tables  created  for  the  Release  2  Intrinsics  should  continue  to  function  without  change, 
but  the  widget  may  wish  to  take  advantage  of  the  new  capabilities  to  fix  some  obscure  bugs. 

In  particular,  it  was  impossible  in  the  Release  2  translation  syntax  to  enter  a  portable  (across 
keyboards)  event  binding  for  most  special  characters.  The  new  syntax  allows,  for  example, 
portable  key  bindings  to  be  made  for  the  "["  and  "]"  keys  independently  of  whether  they 
occur  on  the  same  keycap  or  on  separate  keycaps  on  two  different  keyboards.  Other  new 
capabilities  in  the  translation  manager  should  be  backwards  compatible  with  Release  2. 


E.9  Resource  Name  and  Class  Qualifiers 


In  Release  2,  the  name  and  class  passed  to  xt initialize  were  prepended  to  the  Shell 
widget  name  and  class  to  form  the  full  resource  name  and  class  of  any  resources  required  by 
the  widget  hierarchy.  This  prevented  a  single  process  from  creating  separate  widget  hierar 
chies  that  behaved  as  if  they  were  separate  applications. 

In  Release  3,  the  "application  name"  and  "application  class"  are  no  longer  prepended  to  the 
ApplicationShell  name  and  class.  When  resources  are  retrieved  for  the  widget  hierarchy,  the 
instance  name  and  class  of  the  ApplicationShellWidget  created  by  xtAppCreateShell 
(a  new  routine)  become  the  left-most  resource  name  and  class  qualifiers.  The  compatibility 
interface,  Xtlnitialize,  arranges  to  return  an  ApplicationShellWidget  with  the  appro 
priate  instance  name  and  class  set  from  the  application_class  argument  and  the  com 
mand  line  options. 

The  effect  of  this  change  on  applications  written  to  the  Release  2  specifications  is  that  the 
Shell  name/class  level  of  the  resource  name/class  hierarchy  has  been  removed.  The 
shell_name  argument  to  Xtlnitialize  and  the  name  argument  to  XtCreate- 
ApplicationShell  are  no  longer  evaluated.  No  source  changes  to  application  code 
should  be  required,  but  resource  files  (e.g.,  application-defaults  files)  may  need  to  be  modi 
fied  if  they  explicitly  specify  the  Shell  name  and  class  in  any  resource  specifications. 

In  Release  2,  the  widget  argument  to  XtGetApplicationResources  was  ignored.  In 
Release  3,  it  must  be  specified  as  the  ApplicationShellWidget  instance  that  identifies  the 
name  and  class  of  the  application.  Applications  that  specified  NULL  for  the  widget  argument 
may  not  retrieve  the  resources  that  were  expected. 
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E.10  Bug  Fix  to  XtGet Values 

An  implementation  bug  in  XtGet  Values  in  Release  2  caused  it  to  store  any  resource 
shorter  than  sizeof(long)  into  the  location  specified  in  the  arglist  as  if  the  location  were 
always  declared  as  long. 

Many  applications  (knowingly  or  unknowingly)  relied  on  this  bug  to  clear  the  high-order 
bytes  of  fields  that  were  misdeclared.  Other  applications  encountered  run-time  errors  when 
memory  was  cleared  that  should  not  have  been  cleared. 

In  Release  3,  it  is  critical  to  audit  all  calls  to  XtGet  Values  in  widgets  and  in  applications 
and  verify  that  the  correct  data  type  is  used  in  the  declarations  of  the  variables  named  in  the 
arglists.  The  most  common  errors  involved  declaring  an  int  field  for  the  value  of  xt- 
Nwidth  or  xtNheight  (which  are  Dimension)  or  for  the  value  of  XtNx  and  xtNy 
(which  are  both  Position).  Applications  that  do  not  call  XtGetValues  will  probably 
work  correctly  with  only  a  re-compile. 


E.1 1  Changes  to  Shell  Defaults 

The  default  value  for  the  xtNinput  resource  of  Shell  widgets  is  now  FALSE.  Applications 
that  expect  to  receive  input  and  that  do  not  perform  their  own  X  focus  management  may  need 
to  set  this  to  TRUE  (with  xt  Set  values)  to  operate  under  some  window  managers. 

XtRealizeWidget  now  respects  the  XtNmappedWhenManaged  resource  of  Shell 
widgets.  This  is  unlikely  to  affect  many  applications  (except  those  which  may  have  tried  to 
work  around  the  automatic  MapWindow  request  for  Shells)  but  it  is  possible  that  an  overly- 
general  resource  specification  in  a  resource  database  might  now  prevent  a  hierarchy  from 
being  mapped  when  an  application  expected  other  behavior. 


E.1 2  XtAddlnput  and  XtAddTimeout 

In  Release  2  it  was  not  possible  for  an  application  to  query  the  Toolkit  to  discover  whether  or 
not  there  were  X  events  pending  without  also  executing  input  or  timer  callbacks.  In  Release 
3,  the  routines  XtPending  and  xtPeekEvent  will  only  return  the  state  of  any  X  events 
and  will  not  dispatch  alternate  input  or  timers. 

An  application  that  relied  upon  timer  events  being  dispatched  by  one  of  these  two  routines 
will  have  to  be  modified  to  use  one  of  the  new  routines,  XtProcessEvent  or  xtApp- 
ProcessEvent. 


458  X  Toolkit  Intrinsics  Programming  Manual 


F 


The  xbitmap  Application 


This  appendix  shows  the  complete  code  for  all  versions  of  xbitmap,  which  is 
described  in  Chapters  4  and  5. 


In  This  Appendix: 

The  BitmapEdit  Widget 461 

The  BitmapEdiP.h  Private  Header  File 473 

The  BitmapEdit.h  Public  Header  File 475 

xbitmapS 476 


F 
The  xbitmap  Application 


This  appendix  shows  the  complete  code  for  the  BitmapEdit  widget,  and  the  complete  code 
for  an  advanced  version  of  the  xbitmap  application  which  is  similar  to  xbitmapS  described  in 
Chapter  4  but  adds  the  ability  to  read  XI 1  bitmap  files  (xbitmapS  was  capable  of  writing 
them  only). 

All  source  code  from  this  book  is  available  free  from  numerous  sources,  as  described  in  the 
Preface. 


F.1   The  BitmapEdit  Widget 

Example  F-1.  BitmapEdit:  complete  widget  code 

11     /* 

*  BitmapEdit .c  -  bitmap  editor  widget. 
*/ 

finclude  <Xll/IntrinsicP.h> 
finclude  <Xll/StringDef s.h> 

finclude  <stdio.h> 
finclude  "BitmapEdiP.h" 

fdefine  INTERNAL_WIDTH     2 
idefine  INTERNAL_HEIGHT  4 

fdefine  DEFAULT_PIXMAP_WIDTH   32    /*  in  cells  */ 
fdefine  DEFAULT_PIXMAP_HEIGHT  32    /*  in  cells  */ 

fdefine  DEFAULT_CELL_SIZE      30    /*  in  pixels  */ 

/*  values  for  instance  variable  is_drawn  */ 
fdefine  DRAWN  1 
fdefine  UNDRAWN  0 

:>:•:£:£ 

/*  modes  for  drawing  */ 
fdefine  DRAW  1 
fdefine  UNDRAW  0 

fdefine  MAXLINES  1000     /*  max  of  horiz  or  vertical  cells  */ 
fdefine  SCROLLBARWIDTH  15 

fdefine  of f set (field)  XtOf f set (BitmapEditWidget,  field) 
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Example  F-1.  BitmapEdit:  complete  widget  code  (continued) 

static  XtResource  resources  []  =  { 
{ 

XtN  foreground, 
XtCForeground, 
XtRPixel, 
sizeof  (Pixel)  , 

offset  (bitmapEdit  .  foreground)  , 
XtRString, 
XtDefaultForeground 


XtNcallback, 

XtCCallback, 

XtRCallback, 

sizeof  (caddr_t)  , 

offset  (bitmapEdit  .callback)  , 

XtRCallback, 

NULL 


XtNcellSizelnPixels, 
XtCCellSizelnPixels, 
XtRInt,  sizeof  (int), 

offset  (bitmapEdit  .  cell_size_in_pixels)  , 
XtRImmediate, 
(caddr_t)  DEFAULT_CELL_SIZE 


XtNpixmapWidthlnCells, 
XtCPixmapWidthlnCells, 
XtRDimension, 
sizeof  (Dimension)  , 

offset  (bitmapEdit  ,pixmap_width_in_cells) 
XtRImmediate, 
(caddr_t)  DEFAULTPIXMAPWIDTH 


XtNpixmapHeightlnCells, 
XtCPixmapHeightlnCells, 
XtRDimension, 
sizeof  (Dimension)  , 

offset  (bitmapEdit  .pixmap_height_in_cells) 
XtRImmediate, 
(caddr_t)  DEFAULT_PIXMAP_HEIGHT 


XtNcurX, 
XtCCurX, 
XtRInt, 
sizeof  (int)  , 

offset  (bitmapEdit  .  cur_x) 
XtRImmediate, 
(caddr_t)  0 
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Example  F-1.  BitmapEdit:  complete  widget  code  (continued) 


XtNcurY, 
XtCCurY, 
XtRInt, 
sizeof  (int) , 

offset (bitmapEdit . cur_y ) , 
XtRString, 
(caddr  t)  NULL 


XtNcellArray, 

XtCCellArray, 

XtRString, 

sizeof (String)  , 

offset (bitmapEdit. cell) 

XtRImmediate, 

(caddr_t)  0 


/*  Declaration  of  methods  */ 

/* 

*  These  don't  work  under  SunOS  4.0.1  and  perhaps  others, 

*  static  XtlnitProc  Initialize (); 

*  static  XtExposeProc  Redisplay (); 

*  static  XtWidgetProc  Destroy (); 

*  static  XtWidgetProc  Resize (); 

*  static  XtSetValuesFunc  SetValues (); 


static  void  Initialize  (); 

static  void  Redisplay  (); 

static  void  Destroy (); 

static  void  Resize  (); 

static  Boolean  SetValues (); 

static  XtGeometryResult  QueryGeometry () ; 

/*  these  Core  methods  not  needed  by  BitmapEdit: 

* 

*  static  XtProc  Classlnitialize  (); 

*  static  XtRealizeProc  Realize (); 

*  static  void  Classlnitialize (); 

*  static  void  Realize  (); 
*/ 

/*  the  following  are  private  functions  unique  to  BitmapEdit 
static  void  DrawPixmaps  ()  ,  DoCellO,  ChangeCellSize  ()  ; 

/*  the  following  are  actions  of  BitmapEdit  */ 
static  void  DrawCelK),  UndrawCell  ()  ,  ToggleCell  ()  ; 

/*  The  following  are  public  functions  of  BitmapEdit, 

*  declared  extern  in  the  public  include  file:  */ 
char  *BitmapEditGetArrayString () ; 


static  char  defaultTranslations[]  = 
"<BtnlDown>:     DrawCelK) 
<Btn2Down>:     UndrawCell () 
<Btn3Down>:     ToggleCell () 


\n\ 
\n\ 
\n\ 


Appendix  F:  The  xbitmap  Application 


463 


Example  F-1.  BftmapEdit:  complete  widget  code  (continued) 


<BtnlMotion>:   DrawCell  () 
<Btn2Motion>:   UndrawCelK) 
<Btn3Motion>:   ToggleCell  () 

static  XtActionsRec  actions  []  =  { 
{"DrawCell",  DrawCell}, 
{"UndrawCell",  UndrawCell}, 
{"ToggleCell",  ToggleCell}, 


\n\ 
\n\ 


/*  definition  in  BitmapEdit.h  */ 
static  BitmapEditPointlnf  o  info; 

BitmapEditClassRec  bitmapEditClassRec  =  { 


/*  core  class  fields  */ 

/*  superclass 

*/ 

/*  class  name 

*/ 

/*  widget  size 

*/ 

/*  class_initialize 

*/ 

/*  class  part  initialize*/ 

/*  class_inited 

*/ 

/*  initialize 

*/ 

/*  initialize_hook 

*/ 

/*  realize 

*/ 

/*  actions 

*/ 

/*  num_actions 

*/ 

/*  resources 

*/ 

/*  num  resources 

*/ 

/*  xrm  class 

*/ 

/*  compress  motion 

*/ 

/*  compress  exposure 

*/ 

/*  compress  enterleave 

*/ 

/*  visible  interest 

*/ 

/*  destroy 

*/ 

/*  resize 

*/ 

/*  expose 

*/ 

/*  set  values 

*/ 

/*  set  values  hook 

*/ 

/*  set  values  almost 

*/ 

/*  get  values  hook 

*/ 

/*  accept  focus 

*/ 

/*  version 

*/ 

/*  callback  private 

*/ 

/*  tm_table 

*/ 

/*  query_geometry 

*/ 

/*  display  accelerator 

*/ 

/*  extension 

*/ 

(WidgetClass)  SwidgetClassRec, 

"BitmapEdit", 

sizeof (BitmapEditRec)  , 

NULL, 

NULL, 

FALSE, 

Initialize, 

NULL, 

XtlnheritRealize, 

actions, 

XtNumber (actions)  , 

resources, 

XtNumber (resources)  , 

NULLQUARK, 

TRUE, 

TRUE, 

TRUE, 

FALSE, 

Destroy, 

Resize, 

Redisplay, 

SetValues, 

NULL, 

XtlnheritSetValuesAlmost, 

NULL, 

NULL, 

XtVersion, 

NULL, 

default Translations, 

QueryGeometry, 

XtlnheritDisplayAccelerator, 

NULL 


/*  dummy_field 
}, 


WidgetClass  bitmapEditWidgetClass  =  (WidgetClass)  & 

bitmapEditClassRec; 
static  void 
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Example  F-1.  BitmapEdit:  complete  widget  code  (continued) 

GetDrawGC (cw) 
BitmapEditWidget  cw; 
{ 

XGCValues  values; 

XtGCMask  mask  =  GCForeground  |  GCBackground  I  GCDashOffset 
I  GCDashList  |  GCLineStyle; 

/* 

*  Setting  foreground  and  background  to  1  and  0  looks  like 

*  a  kludge  but  isn't.   This  GC  is  used  for  drawing  into 

*  a  pixmap  of  depth  one.   Real  colors  are  applied  with 

*  a  separate  GC  when  the  pixmap  is  copied  into  the  window. 
*/ 

values. foreground  =  1; 

values. background  =  0; 

values. dashes  =  1; 

values . dash_off set  =  0; 

values. line_style  =  LineOnOf fDash; 

cw->bitmapEdit.draw_gc  =  XCreateGC (XtDisplay (cw)  , 

cw->bitmapEdit .big_picture,  mask,  (values); 
} 

static  void 
GetUndrawGC (cw) 
BitmapEditWidget  cw; 
{ 

XGCValues  values; 

XtGCMask  mask  =  GCForeground  I  GCBackgrpund; 

/*  this  looks  like  a  kludge  but  isn't.   This  GC  is  used  for 

*  drawing  into  a  pixmap  of  depth  one.   Real  colors  are 

*  applied  as  the  pixmap  is  copied  into  the  window. 
*/ 

values . foreground  =  0; 
values .background  =  1; 

cw->bitmapEdit .undraw_gc  =  XCreateGC (XtDisplay (cw) , 
cw->bitmapEdit .big_picture,  mask,  Svalues); 

} 

static  void 
GetCopyGC  (cw) 
BitmapEditWidget  cw; 
{ 

XGCValues  values; 

XtGCMask  mask  =  GCForeground  I  GCBackground; 

values. foreground  =  cw->bitmapEdit . foreground; 
values. background  =  cw->core.background_pixel; 

cw->bitmapEdit .copy_gc  =  XtGetGC(cw,  mask,  Svalues); 
} 

/*  ARGSUSED  */ 

static  void 

Initialize (request,  new) 

BitmapEditWidget  request,  new; 

{ 

new->bitmapEdit . cur_x  =  0; 
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Example  F-1.  BftmapEdit:  complete  widget  code  (continued) 


new->bitmapEdit  .cur_y 
/* 


0; 


/ 


Check  instance  values  set  by  resources 
that  may  be  invalid. 


if  {  (new->bitmapEdit.pixmap_width_in_cells  <  1)  || 

(new->bitmapEdit.pixmap_height_in_cells  <  1))   { 
XtWarning("BitmapEdit:  pixmapWidth  and/or  pixmapHeight  \ 

is  too  small  (using  10  x  10)."); 
new->bitmapEdit.pixmap_width_in_cells  =  10; 
new->bitmapEdit.pixmap_height_in_cells  =  10; 
} 

if  (new->bitmapEdit.cell_size_in_pixels  <  5)  { 

XtWarning("BitmapEdit:  cellsize  is  too  small  (using  5)."); 
new->bitmapEdit  .  cell_size_in_pixels  =  5; 

} 

if  (  (new->bitmapEdit.cur_x  <  0)  |  |   (new->bitmapEdit  .cur_y  <  0) 
XtWarning(-BitmapEdit:  cur_x  and  cur_y  must  be  \ 

non-negative  (using  0,  0)."); 
new->bitmapEdit  .  cur_x  =  0; 
new->bitmapEdit  .  cur_y  =  0; 

} 

if  (new->bitmapEdit.cell  ==  NULL) 
new->bitmapEdit  .  cell  = 

XtCalloc  (new->bitmapEdit  .pixmap_width_in_cells 

*  new->bitmapEdit.pixmap_height_in_cells, 
sizeof  (char)  )  ; 

new->bitmapEdit.pixmap_width_in_pixels  = 

new->bitmapEdit  .pixmap_width_in_cells 

*  new->bitmapEdit.cell_size_in_pixels; 

new->bitmapEdit.pixmap_height_in_pixels  = 

new->bitmapEdit.pixmap_height_in_cells 

*  new->bitmapEdit.cell_size_in_pixels; 

if  (new->core.  width  ==  0) 

new->core.  width  =  (new->bitmapEdit  .pixmap_width_in_pixels 

>  300)  ?  300  : 

(new->bitmapEdit  .pixmap_width_in_pixels)  ; 
if  (new->core.  height  ==  0) 

new->core.  height  =  (new->bitmapEdit  .pixmap_height_in_pixels 

>  300)  ?  300  : 

(new->bitmapEdit  .pixmap_height_in_pixels)  ; 

CreateBigPixmap  (new)  ; 

GetDrawGC  (new)  ; 
GetUndrawGC  (new)  ; 
GetCopyGC  (new)  ; 

DrawIntoBigPixmap  (new)  ; 


/*  ARGSUSED 
static  void 
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Example  F-1.  BitmapEdit:  complete  widget  code  (continued) 

Redisplay  (cw,  event) 
BitmapEditWidget  cw; 
XExposeEvent  *event; 
{ 

register  int  x,  y; 

unsigned  int  width,  height; 

if  (.'XtlsRealized(cw)  ) 
return; 

if  (event)  {   /*  called  from  btn-event  or  expose  */ 

x  =  event->x; 

y  =  event->y; 

width  =  event->width; 

height  =   event->height; 
} 
else  {         /*  called  because  complete  redraw  */ 

x  =  0; 

y  =  0; 

width  =  cw->bitmapEdit  .  pixmap_width_in_pixels; 

height  =  cw->bitmapEdit  .pixmap_height_in_pixels; 
} 

if  (DefaultDepthOfScreen(XtScreen(cw)  )  ==  1) 

XCopyArea  (XtDisplay  (cw)  ,  cw->bitmapEdit  .big_picture, 
XtWindow  (cw)  ,  cw->bitmapEdit  .  copy_gc,  x  + 
cw->bitmapEdit  .  cur_x,  y  +  cw->bitmapEdit  .  cur_y, 
width,  height,  x,  y)  ; 
else 

XCopyPlane  (XtDisplay  {cw)  ,  cw->bitmapEdit  .big_picture, 
XtWindow  (cw)  ,  cw->bitmapEdit  .  copy_gc,  x  + 
cw->bitmapEdit  .  cur_x,  y  +  cw->bitmapEdit  .cur_y, 
width,  height,  x,  y,  1); 


/*  ARGSUSED  */ 

static  Boolean 

SetValues  (current,  request,  new) 

Widget  current,  request,  new; 

{ 

BitmapEditWidget  curcw  =  (BitmapEditWidget)  current; 

BitmapEditWidget  newcw  =  (BitmapEditWidget)  new; 

Boolean  do_redisplay  =  False; 

if  (curcw->bitmapEdit  .  foreground  != 

newcw->bitmapEdit  .  foreground)  { 
XtReleaseGC  (curcw,  curcw->bitmapEdit  .  copy_gc) 
GetCopyGC  (newcw)  ; 
do_redi  splay  =  True; 

} 

if  (  (curcw->bitmapEdit  .  cur_x  != 

newcw->bitmapEdit  .  cur_x)  I  I 
(curcw->bitmapEdit  .  cur_y  != 

newcw->bitmapEdit  .cur_y)  )  { 

do_redisplay  =  True; 
} 

if  (curcw->bitmapEdit  .  cell_size_in_pixels  != 
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Example  F-1.  BitmapEdit:  complete  widget  code  (continued) 

newcw->bitmapEdit  .  cell_size_in_pixels) 
ChangeCellSize  (curcw, 

newcw->bitmapEdit  .  cell_size_in_pixels)  ; 
do_redisplay  =  True; 


if  (curcw->bitmapEdit  .pixmap_width_in_cells  != 

newcw->bitmapEdit  .  pixmap_width_in_cells)   { 
newcw->bitmapEdit  .  pixmap_width_in_cells  = 

curcw->bitmapEdit  .  pixmap_width_in_cells; 
XtWarning  ("BitmapEdit  :  pixmap_width_in_cells  cannot  \ 

be  set  by  XtSetValues.  \n")  ; 
} 

if  (curcw->bitmapEdit  .pixmap_height_in_cells  != 

newcw->bitmapEdit  .pixmap_height_in_cells)  { 
newcw->bitmapEdit  .  pixmap_height_in_cells  = 

curcw->bitmapEdit  .pixmap_height_in_cells; 
XtWarning  ("BitmapEdit  :  pixmap_height_in_cells  cannot  \ 

be  set  by  XtSetValues.  \n")  ; 
} 

return  do_redisplay; 


static  void 
Destroy  (cw) 
BitmapEditWidget  cw; 
{ 

if  (cw->bitmapEdit  .big_picture) 

XFreePixmap(XtDisplay  (cw)  ,  cw->bitmapEdit  .big_picture)  ; 

if  (cw->bitmapEdit  .draw_gc) 

XFreeGC  (XtDisplay  (cw)  ,  cw->bitmapEdit  .draw_gc)  ; 

if  (cw->bitmapEdit  .undraw_gc) 

XFreeGC  (XtDisplay  (cw)  ,  cw->bitmapEdit  .undraw_gc)  ; 

if  (cw->bitmapEdit  .  copy_gc) 

XFreeGC  (XtDisplay  (cw)  ,  cw->bitmapEdit  .  copy_gc)  ; 

/*  NOTE!   This  should  only  free  when  the  application  didn't 
*  allocate  it.   Need  to  add  another.   */ 

XtFree  (cw->bitmapEdit  .  cell)  ; 
} 

static  void 
DrawCell  (w,  event) 
BitmapEditWidget  w; 
XEvent  *event; 
( 

DrawPixmaps  (w->bitmapEdit  .draw_gc,  DRAW,  w,  event); 
} 

static  void 
UndrawCell  (w,  event) 
BitmapEditWidget  w; 
XEvent  *event; 
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Example  F-1.  BitmapEdit:  complete  widget  code  (continued) 

DrawPixmaps (w->bitmapEdit.undraw_gc,  UNDRAW,  w,  event); 

static  void 
ToggleCell (w,  event) 
BitmapEditWidget  w; 
XEvent  *event; 

static  int  oldx  =  -1,  oldy  =  -1; 

GC  gc; 

int  mode; 

int  newx,  newy; 

/*  This  is  strictly  correct,  but  doesn't 

*  seem  to  be  necessary  */ 
if  (event->type  ==  ButtonPress)  { 

newx  =  (w->bitmapEdit.cur_x  +  ((XButtonEvent  *) event )->x)  / 

w->bitmapEdit . cell_size_in_pixels; 

newy  =  (w->bitmapEdit . cur_y  +  ((XButtonEvent  *) event )->y)  / 
w->bitmapEdit . cell_size_in_pixels; 

else   { 

newx  =  (w->bitmapEdit .cur_x  +  ((XMotionEvent  *) event )->x)  / 

w->bitmapEdit . cell_size_in_pixels; 
newy  =  (w->bitmapEdit . cur_y  +  ((XMotionEvent  *) event) ->y)  / 

w->bitmapEdit . cell_size_in_pixels; 


if  ((mode  =  w->bitmapEdit  .  cell  [newx  +  newy  * 
w->bitmapEdit.pixmap_width_in_cells]  ) 

gc  =  w->bitmapEdit  .undraw_gc; 

mode  =  UNDRAW; 
} 
else  { 

gc  =  w->bitmapEdit  .draw_gc; 

mode  =  DRAW; 


==  DRAWN)  { 


if  (oldx  !=  newx  |  |  oldy  !=  newy)  { 
oldx  =  newx; 
oldy  =  newy; 
DrawPixmaps  (gc,  mode,  w,  event) 


static  void 

DrawPixmaps  (gc,  mode,  w,  event) 

GC  gc; 

int  mode; 

BitmapEditWidget  w; 

XButtonEvent  *event; 

{ 

int  newx  =  (w->bitmapEdit  .  cur_x  +  event->x)  / 

w->bitmapEdit  .  cell_size_in_pixels; 
int  newy  =  (w->bitmapEdit  .cur_y  +  event->y)  / 

w->bitmapEdit  .  cell_size_in_pixels; 
XExposeEvent  f.ake_event; 
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Example  F-1.  BitmapEdit:  complete  widget  code  (continued) 

/*  if  already  done,  return  */ 
if  (w->bitmapEdit . cell [newx  +  newy  * 

w->bitmapEdit .pixmap_width_in_cells]  ==  mode) 
return; 

/*  otherwise,  draw  or  undraw  */ 

XFillRectangle (XtDisplay (w) ,  w->bitmapEdit .big_picture,  gc, 
w->bitmapEdit . cell_size_in_pixels*newx  +  2, 
w->bitmapEdit . cell_size_in_pixels*newy  +  2, 
(unsigned  int) w->bitmapEdit . cell_size_in_pixels  -  3, 
(unsigned  int ) w->bitmapEdit . cell_size_in_pixels  -3); 

w->bitmapEdit . cell [newx  +  newy  * 

w->bitmapEdit .pixmap_width_in_cells]  =  mode; 
info. mode  =  mode; 
info. newx  =  newx; 
info. newy  =  newy; 

fake_event.x  =  w->bitmapEdit . cell_size_in_pixels  * 

newx  -  w->bitmapEdit . cur_x; 
fake_event.y  =  w->bitmapEdit . cell_size_in_pixels  * 

newy  -  w->bitmapEdit . cur_y; 

fake_event .width  =  w->bitmapEdit . cell_size_in_pixels; 
fake_event . height  =  w->bitmapEdit . cell_size_in_pixels; 

Redisplay  (w,  &fake_event) ; 
XtCallCallbacks(w,  XtNcallback,  Sinfo) ; 
} 

CreateBigPixmap (cw) 
BitmapEditWidget  cw; 
{ 

/*  always  a  1  bit  deep  pixmap,  regardless  of  screen  depth  */ 
cw->bitmapEdit .big_picture  =  XCreatePixmap (XtDisplay (cw) , 

RootWindow (XtDisplay (cw) ,  Def aultScreen  (XtDisplay  (cw) ) ) 
cw->bitmapEdit .pixmap_width_in_pixels  +  2, 
cw->bitmapEdit . pixmap_height_in_pixels  +2,  1); 
} 

DrawIntoBigPixmap (cw) 
BitmapEditWidget  cw; 
{ 

int  n_horiz_segments,  n_vert_segments; 

XSegment  segment [MAXLINES] ; 

register  int  x,  y; 

n_horiz_segments  =  cw->bitmapEdit .pixmap_height_in_cells  +  1; 
n_vert_segments  =  cw->bitmapEdit .pixmap_width_in_cells  +  1; 

for  (x  =  0;  x  <  n_horiz_segments;  x++)  { 

segment [x] .xl  =  0; 

segment [x] .x2  =  cw->bitmapEdit .pixmap_width_in_pixels; 

segment [x] .yl  =  cw->bitmapEdit . cell_size_in_pixels  *  x; 

segment [x] .y2  =  cw->bitmapEdit . cell_size_in_pixels  *  x; 
} 

XDrawSegments (XtDisplay (cw) ,  cw->bitmapEdit .big_picture, 

cw->bitmapEdit .draw  gc,  segment,  n  horiz_segments) ; 
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Example  F-1.  BitmapEdit:  complete  widget  code  (continued) 

for  (y  =  0;  y  <  n_vert_segments;  y++)  { 

segment [y] .xl  =  y  *  cw->bitmapEdit . cell_size_in_pixels; 
segment [y] .x2  =  y  *  cw->bitmapEdit . cell_size_in_pixels; 
segment [y] .yl  =  0; 
segment [y] .y2  =  cw->bitmapEdit .pixmap_height_in_pixels; 

XDrawSegments (XtDisplay (cw) ,  cw->bitmapEdit .big_picture, 

cw->bitmapEdit . draw_gc,  segment,  n_vert_segments) ; 

/*  draw  current  cell  array  into  pixmap  */ 

for  (x  =  0;  x  <  cw->bitmapEdit .pixmap_width_in_cells;  x++)  { 

for  (y  =  0;  y  <  cw->bitmapEdit .pixmap_height_in_cells;  y++)  { 
if  (cw->bitmapEdit.cell [x  + 

(y  *  cw->bitmapEdit .pixmap_width_in_cells) ] 
==  DRAWN) 

DoCell (cw,  x,  y,  cw->bitmapEdit .draw_gc) ; 
else 

DoCell (cw,  x,  y,  cw->bitmapEdit .undraw_gc) ; 
} 
} 

/*  A  Public  function,  not  static  */ 
char  * 

BitmapEditGetArrayString (w) 
BitmapEditWidget  w; 

return  (w->bitmapEdit . cell)  ; 

/*  ARGSUSED  */ 
static  void 
Resize (cw) 
BitmapEditWidget  cw; 

/* 

*  resize  does  nothing  unless  new  size 

*  is  bigger  than  entire  pixmap 
*/ 

if  ( (cw->core. width  >  cw->bitmapEdit .pixmap_width_in_pixels)  && 
(cw->core. height  > 
cw->bitmapEdit ,pixmap_height_in_pixels)  )  { 

/* 

*  Calculate  the  maximum  cell  size  that  will  allow  the 

*  entire  bitmap  to  be  displayed. 

*/ 
Dimension  w_temp_cell_size_in_pixels, 

h_temp_cell_size_in_pixels; 
Dimension  new_cell_size_in_pixels; 

w_temp_cell_size_in_pixels  =  cw->core. width  / 
cw->bitmapEdit . pixmap_width_in_cells; 

h_temp_cell_size_in_pixels  =  cw->core .height  / 
cw->bitmapEdit.pixmap_height_in_cells; 

if  (w_temp_cell_size_in_pixels  <  h_temp_cell_size_in_pixels) 
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Example  F-1.  BitmapEdit:  complete  widget  code  (continued) 

new_cell_size_in_pixels  =  w_temp_cell_size_in_pixels; 
else 

new_cell_size_in_pixels  =  h_temp_cell_size_in_pixels; 

/*  if  size  change  mandates  a  new  pixmap,  make  one  */ 
if  (new_cell_size_in_pixels  != 
cw->bitmapEdit . cell_size_in_pixels) 

ChangeCellSize (cw,  new_cell_size_in_pixels) ; 


static  void 

ChangeCellSize (cw,  new_cell_size) 

BitmapEditWidget  cw; 

int  new_cell_size; 

< 

int  x,  y; 

cw->bitmapEdit . cell_size_in_pixels  =  new_cell_size; 

/*  recalculate  variables  based  on  cell  size  */ 
cw->bitmapEdit .pixmap_width_in_pixels  = 

cw->bitmapEdit .pixmap_width_in_cells  * 

cw->bitmapEdit . cell_size_in_pixels; 

cw->bitmapEdit .pixmap_height_in_pixels  = 

cw->bitmapEdit . pixmap_height_in_cells  * 
cw->bitmapEdit . cell_size_in_pixels; 

/*  destroy  old  and  create  new  pixmap  of  correct  size  */ 
XFreePixmap (XtDisplay (cw) ,  cw->bitmapEdit .big_picture) ; 
CreateBigPixmap (cw) ; 

/*  draw  lines  into  new  pixmap  */ 
DrawIntoBigPixmap (cw) ; 

/*  draw  current  cell  array  into  pixmap  */ 

for  (x  =  0;  x  <  cw->bitmapEdit .pixmap_width_in_cells;  x++)  { 

for  (y  =  0;  y  <  cw->bitmapEdit .pixmap_height_in_cells;  y++)  { 
if  (cw->bitmapEdit.cell [x  + 

(y  *  cw->bitmapEdit .pixmap_width_in_cells) ] 
==  DRAWN) 
DoCell (cw,  x,  y,  cw->bitmapEdit .draw  gc) ; 


else 


DoCell  (cw,  x,  y,  cw->bitmapEdit .undraw_gc) ; 


} 


static  void 

DoCell  (w,  x,  y,  gc) 

BitmapEditWidget  w; 

int  x,  y; 

GC  gc; 

{ 

/*  otherwise,  draw  or  undraw  */ 

XFillRectangle (XtDisplay (w) ,  w->bitmapEdit .big_picture,  gc, 
w->bitmapEdit .cell_size  in_pixels  *  x  +  2, 
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Example  F-1.  BitmapEdit:  complete  widget  code  (continued) 

w->bitmapEdit.cell_size_in_pixels  *  y  +  2, 
(unsigned  int)  w->bitmapEdit  .  cell_size_in_pixels  -  3, 
(unsigned  int)  w->bitmapEdit  .  cell_size_in_pixels  -  3) 


static  XtGeometryResult  QueryGeometry  (w,  proposed,  answer) 
BitmapEditWidget  w; 

XtWidgetGeometry  *proposed,  *answer; 
{ 

answer->request_mode  =  CWWidth  |  CWHeight; 

/*  initial  width  and  height  */ 

answer->width  =  (w->bitmapEdit  .pixmap_width_in_pixels  >  300) 

?  300  :  w->bitmapEdit  .pixmap_width_in_pixels; 
answer->height  =  (w->bitmapEdit  .pixmap_height_in_pixels  >  300) 

?  300  :  w->bitmapEdit  .pixmap_height_in_pixels; 

if  (   (  (proposed->request_mode  &  (CWWidth  |  CWHeight)) 
==  (CWWidth  |  CWHeight))  && 

proposed->width  ==  answer->width  && 
proposed->height  ==  answer->height) 
return  XtGeometryYes; 
else  if  (answer->width  ==  w->core.  width  s& 

answer->heignt  ==  w->core.  height) 
return  XtGeometryNo; 
else 

return  XtGeometryAlmost; 


F.2  The  BitmapEdiP.h  Private  Header  File 

Example  F-2.  BitmapEdiP.h:  complete  private  header  file 

/* 

*  Copyright  1989  O'Reilly  and  Associates,  Inc. 

*  See  ../Copyright  for  complete  rights  and  liability  information. 
*/ 

/* 

*  Copyright  1989  O'Reilly  and  Associates,  Inc. 

*  See  ../Copyright  for  complete  rights  and  liability  information. 
*/ 

/* 

*  BitmapEditP.h  -  Private  definitions  for  BitmapEdit  widget 
*/ 

fifndef  _ORABitmapEditP_h 
fdefine  _ORABitmapEditP_h 

/* 

*  This  include  not  needed  unless  the  .c  file  includes  Intrinsic?. h 

*  after  this  file.    Anyway,  it  doesn't  hurt. 
*/ 
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Example  F-2.  BitmapEdiP.h:  complete  private  header  file  (continued) 

linclude  <Xll/CoreP .h> 

/* 

*  This  one  is  always  needed! 
*/ 

finclude  "BitmapEdit .h" 

/*  New  fields  for  the  BitmapEdit  widget  class  record  */ 

typedef  struct  { 

int  make_compiler_happy;  /*  keep  compiler  happy  */ 
}  BitmapEditClassPart; 

/*  Full  class  record  declaration  */ 
typedef  struct  _BitmapEditClassRec  { 

CoreClassPart    core_class; 

BitmapEditClassPart   bitmapEdit_class; 
}  BitmapEditClassRec; 

extern  BitmapEditClassRec  bitmapEditClassRec; 

/*  New  fields  for  the  BitmapEdit  widget  record  */ 
typedef  struct  { 

/*  resources  */ 

Pixel  foreground; 

XtCallbackList  callback;   /*  application  installed  callback  fnct(s)  */ 

Dimension   pixmap_width_in_cells; 

Dimension   pixmap_height_in_cells; 

int  cell_size_in_pixels; 

int  cur_x,  cur_y;   /*  position  of  visible  corner  in  big  pixmap  */ 

char  *cell;      /*  array  for  keeping  track  of  array  of  bits  */ 

/*  private  state  */ 

Dimension   pixmap_width_in_pixels; 
Dimension   pixmap_height_in_pixels; 
Pixmap  big_picture; 

GC          draw_gc;   /*  one  plane,  for  drawing  into  pixmap  */ 
GC         undraw_gc;/*  one  plane,  for  drawing  into  pixmap  */ 

GC          copy_gc;   /*  defaultdepthof screen,  for  copy'g  p'map  into  wndow  */ 
}  BitmapEditPart; 

/* 

*  Full  instance  record  declaration 
*/ 

typedef  struct  _BitmapEditRec  { 

CorePart         core; 

BitmapEditPart   bitmapEdit; 
}  BitmapEditRec; 

fendif  /*  _ORABitmapEditP_h  */ 
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F.3  The  BitmapEdit.h  Public  Header  File 


Example  F-3.  BitmapEd'rt.h:  complete  public  header  Hie 

fifndef  _ORABitmapEdit_h 
fdefine  _ORABitmapEdit_h 


*  BitmapEdit  Widget  public  include  file 
*/ 


This  include  not  needed  unless  the  application  includes 
Intrinsic. h  after  this  file.    Anyway,  it  doesn't  hurt. 


tinclude  <Xll/Core.h> 

/*  Resources: 

*  Name 

* 

*  (from  RectObj) 

*  ancestorSensitive 


Class 


RepType 


Ancestor- 
Sensitive 
Position 


* 

y 

Position 

int 

* 

width 

Dimension 

unsignei 

* 

height 

Dimension 

unsignei 

* 

borderWidth 

BorderWidth 

* 

sensitive 

Sensitive 

* 

* 

(from  Core) 

* 

screen 

Screen 

Pointer 

* 

depth 

Depth 

Int 

* 

colormap 

Colormap 

Pointer 

* 

background 

Backgroun 

pixel 

* 

backgroundPixmap 

Pixmap 

Pixmap 

* 

borderColor 

BorderColor 

pixel 

* 

borderPixmap 

BorderPixmap 

Pixmap 

* 

mappedWhenManaged 

MappedWhen 

Boolean 

Managed 

translations 
accelerators 

(from  BitmapEdit) 

foregroundPixel 

backgroundPixel 

callback 

cellSize 

pixmapWidth 

pixmapHeight 


Foreground 

Background 

Callback 

CellSize 

PixmapWidth 

PixmapHeight 


pixel 

pixel 

Callback 

int 

int 

int 


•I 


Default  Value 


int  0 

0 

t   0 
t   0 


Xt Copy Screen 

XtCopyFromParent 

XtCopyFromParent 

White 

XtUnspecified- 

Pixmap 
Black 
XtUnspecif ied- 

Pixmap 
True 


Black 

White 

NULL 

30 

32 

32 


This  public  structure  is  used  as  call_data  to  the  callback. 
It  passes  the  x,  y  position  of  the  cell  toggled  (in  units  of 
cells,  not  pixels)  and  a  mode  flag  that  indicates  whether  the 
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Example  F-3.  B'rtmapEd'rt.h:  complete  public  header  file  (continued) 

*  cell  was  turned  on  (1)  or  off  (0) . 
*/ 

typedef  struct  { 
int  mode; 
int  newx; 
int  newy; 
}  BitmapEditPointlnfo; 

fdefine  XtNcellSizelnPixels    "cellSizelnPixels" 

fdefine  XtNpixmapWidthlnCells  "pixmapWidthlnCells" 

fdefine  XtNpixmapHeightlnCells      "pixmapHeightlnCells" 

fdefine  XtNcurX  "curX" 

fdefine  XtNcurY  "curY" 

fdefine  XtNcellArray  "cellArray" 

fdefine  XtCCellSizelnPixels    "CellSizelnPixels" 

fdefine  XtCPixmapWidthlnCells  "PixmapWidthlnCells" 

fdefine  XtCPixmapHeightlnCells      "PixmapHeightlnCells" 

fdefine  XtCCurX  "CurX" 

fdefine  XtCCurY  "CurY" 

fdefine  XtCCellArray  "CellArray" 

extern  char  *BitmapEditGetArrayString () ;  /*  w  */ 
/*  Widget  w;  */ 

/*  Class  record  constants  */ 

extern  WidgetClass  bitmapEditWidgetClass; 

typedef  struct  _BitmapEditClassRec  *BitmapEditWidgetClass; 
typedef  struct  _BitmapEditRec       *BitmapEditWidget; 

fendif  /*  _ORABitmapEdit_h  */ 

/*  DON'T  ADD  STUFF  AFTER  THIS  fendif  */ 


F.4  xbitmapS 


Example  F-4.  xbitmapS:  complete  application  code 

/* 

*  xbitmapS. c 

*/ 

finclude  <Xll/Intrinsic.h> 
finclude  <Xll/StringDef s.h> 

fifdef  X11R3 
finclude  <Xll/Form.h> 
finclude  <Xll/Box.h> 
finclude  <Xll/Command.h> 
felse  /*  R4  or  later  */ 
finclude  <Xll/Xaw/Form.h> 
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Example  F-4.  xbitmapS:  complete  application  code  (continued) 

finclude  <Xll/Xaw/Box.h> 
finclude  <Xll/Xaw/Command.h> 
fendif  /*  X11R3  */ 

finclude  "BitmapEdit .h" 
finclude  <stdio.h> 

fdefine  DRAWN  1 
fdefine  UNDRAWN  0 

GC  draw_gc,  undraw_gc,  invert_gc; 

Pixmap  normal_bitmap; 

Widget  bigBitmap,  showNormalBitmap,  showReverseBitmap; 

Dimension  pixmap_width_in_cells,  pixmap_height_in_cells; 

static  void  cell_toggled () ; 

String  filename;     /*  filename  to  read  and  write  */ 
static  Boolean  f ile_contained_good_data  =  False; 

/*  ARGSUSED  */ 

static  void 

printout (widget,  client_data,  call_data) 

Widget  widget; 

caddr_t  client_data,  call_data;     /*  unused  */ 

XWriteBitmapFile (XtDisplay (widget) ,  filename,  normal_bitmap, 
pixmap_width_in_cells,  pixmap_height_in_cells,  0,  0)  ; 

static  void 

redraw_small_picture (w) 
Widget  w; 

GC  gc; 

if  (w  ==  showNormalBitmap) 

gc  =  DefaultGCOf Screen (XtScreen (w) ); 
else 

gc  =  invert_gc; 

if  (Def aultDepthOf Screen (XtScreen (w) )  ==  1) 

XCopyArea (XtDisplay (w) ,  normal_bitmap,  XtWindow(w), 

gc,  0,  0,  pixmap_width_in_cells, 

pixmap_height_in_cells,  0,  0); 
else 

XCopyPlane (XtDisplay  (w) ,  normal_bitmap,  XtWindow(w), 

gc,  0,  0,  pixmap_width_in_cells, 

pixmap_height_in_cells,  0,  0,  1); 

String 
FillCell (w) 
Widget  w; 
| 

String  cell; 

int  x,  y; 

Xlmage  * image; 

cell  =  XtCalloc(pixmap_width_in_cells  *  pixmap_height_in_cells, 
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Example  F-4.  xbitmapS:  complete  application  code  (continued) 

sizeof  (char) ) ; 
/*  Convert  pixmap  into  image,  so  that  we  can 

*  read  indiviual  pixels  */ 
image  =  XGetlmage (XtDisplay (w) ,  normal_bitmap,  0,  0, 

pixmap_width_in_cells,  pixmap_height_in_cells, 
AllPlanes,  XYPixmap); 

for  (x  =  0;  x  <  pixmap_width_in_cells;  x++)  { 
for  (y  =  0;  y  <  pixmap_height_in_cells;  y 

cell [x  +  (y  *  pixmap_width_in_cells) ] 
i 


in_cells;  y+  +  )  { 

i_in_cells) ]  =  XGetPixel (image,  x,  y) 


return  (cell) ; 

main (argc,  argv) 
int  argc; 
char  *argv [ ] ; 

Widget  topLevel,  form,  buttonbox,  quit,  output; 
Arg  args [5] ; 
int  i; 

extern  exit(); 

unsigned  int  width,  height;     /*  NOT  Dimension:  used  in  Xlib  calls  */ 
int  junk; 
String  cell; 

static  XtActionsRec  window_actions [  ]  =  { 
{ "redraw_small_picture",  redraw_small_picture} 

String  trans  = 
"<Expose> :      redraw_small_picture ( ) "; 

static  XrmOptionDescRec  table []  = 

{"-pw",  "*pixmapWidthInCells",  XrmoptionSepArg,  NULL}, 

{ "-pixmapwidth" ,  "*pixmapWidthInCells",  XrmoptionSepArg,  NULL}, 

{"-ph",  "*pixmapHeightInCells" ,  XrmoptionSepArg,  NULL}, 

{ "-pixmapheight" ,  "*pixmapHeightInCells" ,  XrmoptionSepArg,  NULL}, 

{"-cellsize",  "*cellSize!nPixels",  XrmoptionSepArg,  NULL}, 


topLevel  =  Xtlnitialize (argv [ 0] ,  "XBitmapS",  table,  XtNumber (table) , 
targe,  argv) ; 

if  (argv[l]  !=  NULL) 

filename  =  argv[l]; 
else  { 

fprintf (stderr,  "xbitmap:  must  specify  filename  \ 
on  command  line.\nn); 

exit  (1) ; 
} 

form  =  XtCreateManagedWidget ( "f orm" ,  f ormWidgetClass,  topLevel, 
NULL,  0) ; 

buttonbox  =  XtCreateManagedWidget ("buttonbox",  boxWidgetClass, 
form,  NULL,  0) ; 
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Example  F-4.  xbitmapS:  complete  application  code  (continued) 

output  =  XtCreateManagedWidget  ("output",  commandWidgetClass, 
buttonbox,  NULL,  0); 

XtAddCallback  (output,  XtNcallback,  printout,  NULL); 

quit  =  XtCreateManagedWidget  ("quit",  commandWidgetClass, 
buttonbox,  NULL,  0)  ; 

XtAddCallback  (quit,  XtNcallback,  exit,  NULL); 
XtAddActions  (window_actions,  XtNumber  (window_actions)  )  ; 

switch  (XReadBitmapFile  (XtDisplay  (quit)  , 

RootWindowOfScreen  (XtScreen  (quit)  )  ,  filename, 
Swidth,  sheight,  snormal_bitmap,  Sjunk,  &junk))  { 
case  BitmapSuccess  : 

f  ile_contained_good_data  =  True; 

if  (  (pixmap_width_in_cells  !=  width)  || 

(pixmap_height_in_cells  !=  height))  { 
fprintf  (stderr,  "xbitmap:  bitmap  \ 

file  dimensions  do  not  match  \ 
resource  database,  ignoring  \ 
database  .  \n"  )  ; 
i  =  0; 
XtSetArg(args[i]  ,  XtNpixmapWidthlnCells, 

width)  ;    i++; 
XtSetArg  (args  [i  ]  ,  XtNpixmapHeightlnCells, 

height);    i++; 

pixmap_width_in_cells  =  width; 
pixmap_height_in_cells  =  height; 
cell  =  FillCell(quit)  ; 

XtSetArg  (args  [i  ],  XtNcellArray,  cell);    i++; 
} 

break; 
case  BitmapOpenFailed: 

fprintf  (stderr,  "xbitmap:  could  not  open  \ 

bitmap  file,  using  fresh  bitmap.  \n") 
break; 
case  BitmapFilelnvalid: 

fprintf  (stderr,  "xbitmap:  bitmap  file  invalid.  \n")  ; 
exit(l); 
case  BitmapNoMemory  : 

fprintf  (stderr,  "xbitmap:  insufficient  \ 

server  memory  to  create  bitmap.  \n")  ; 
exit  (1); 
default: 

fprintf  (stderr,  "xbitmap:  programming  error.  \n"); 
exit(l); 


/*  args  are  set  in  if  and  switch  above  if  file  was  read  */ 
bigBitmap  =  XtCreateManagedWidget  ("bigBitmap", 

bitmapEditWidget  Class, 

form,  args,  i)  ; 

XtAddCallback  (bigBitmap,  XtNcallback,  cell_toggled,  NULL); 

if  (  !  file_contained_good_data)  { 
i  =  0; 
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Example  F-4.  xbitmapS:  complete  application  code  (continued) 

XtSetArg (args [i] ,  XtNpixmapHeightlnCells, 

ipixmap_height_in_cells) ;    i++; 
XtSetArg (args [i] ,  XtNpixmapWidthlnCells, 

£pixmap_width_in_cells) ;    i++; 
XtGetValues (bigBitmap,  args,  i); 

normal_bitmap  =  XCreatePixmap (XtDisplay (quit) , 
RootWindowOfScreen (XtScreen (quit)  )  , 

pixmap_width_in_cells,  pixmap_height_in_cells,  1) j 
} 

set_up_things (topLevel) ; 

i  =  0; 

XtSetArg (args [i] ,  XtNwidth,  pixmap_width_in_cells) ;     i++; 
XtSetArg (args [i] ,  XtNheight,  pixmap_height_in_cells) ;     i++; 
XtSetArg (args [i] ,  XtN translations, 

XtParseTranslationTable (trans) ) ;     i++; 
showNormalBitmap  =  XtCreateManagedWidget ("showNormalBitmap", 

widgetclass,  buttonbox,  args,  i); 

showReverseBitmap  =  XtCreateManagedWidget ("showReverseBitmap" 
widgetclass,  buttonbox,  args,  i); 

XtRealizeWidget  (topLevel) ; 
XtMainLoopO  ; 

} 

set_up_things (w) 

Widget  w; 

{ 

XGCValues  values; 

values . foreground  =  1; 
values .background  =  0; 

/*  note  that  normal_bitmap  is  used  as  the  drawable 

*  because  it  is  one  bit  deep.   The  root  window  may 

*  not  be  one  bit  deep.  */ 

draw_gc  =  XCreateGC (XtDisplay (w) ,  normal_bitmap, 
GCForeground  |  GCBackground,  Svalues) ; 

values . foreground  =  0; 
values. background  =  1; 

undraw_gc  =  XCreateGC (XtDisplay (w) ,  normal_bitmap, 
GCForeground  |  GCBackground,  lvalues) ; 

/*  this  GC  is  for  copying  from  the  bitmap 

*  to  the  small  reverse  widget  */ 

values. foreground  =  WhitePixelOf Screen  (XtScreen (w) ); 
values. background  =  BlackPixelOfScreen (XtScreen (w) ); 
invert_gc  =  XtGetGC(w,  GCForeground  |  GCBackground,  Svalues) 
J 

/*  ARGSUSED  */ 

static  void 

cell_toggled (w,  unused,  info) 

Widget  w; 

caddr_t  unused;      /*  client_data  */ 

caddr  t  info;   /*  call  data  (from  widget)  */ 
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Example  F-4.  xbitmapS:  complete  application  code  (continued) 


BitmapEditPointlnfo  *cur_info  =  (BitmapEditPointlnfo  *)  info 
/* 

*  Note:  BitmapEditPointlnfo  is  defined  in  BitmapEdit.h 
*/ 

XDrawPoint  (XtDisplay  (w)  ,  normal_bitmap,  (  (cur_info->mode  == 
DRAWN)  ?  draw_gc  :  undraw_gc)  ,  cur_info->newx, 
cur_inf  o->newy)  ; 

redraw_small_picture  (showNormalBitmap)  ; 
redraw_small_picture  (showReverseBitmap)  ; 
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This  appendix  describes  where  you  can  get  more  information  about  the  X 
Toolkit  and  about  X  in  general,  including  other  books  on  the  subject  and  the 
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G 

Sources  of  Additional  Information 


This  appendix  lists  a  few  of  the  official  and  unofficial  sources  for  information  about  the  X 
Window  System  and  associated  software. 

Note  that  some  of  this  detailed  information  may  become  dated  rather  quickly.  The  best 
source  of  current  information  is  the  comp. windows jc  network  news  group,  described  later  in 
this  appendix. 


G.1   Getting  the  X  Software 

At  this  writing,  the  current  public  release  level  is  Release  3,  but  Release  4  is  expected  to  be 
released  shortly.  This  book  documents  Release  3,  with  some  references  to  Release  4.  The 
references  to  R4  are  based  on  the  Beta  releases  of  R4  currently  available  to  X  Consortium 
members  only.  (O'Reilly  and  Associates,  Inc.,  is  an  X  Consortium  Affiliate  Member.)  Even 
after  the  public  R4  release,  many  people  will  continue  to  use  R3  since  there  is  a  considerable 
lag  time  between  the  date  that  MIT  distributes  a  new  release  and  the  date  by  which  vendors 
integrate  that  release  into  their  own  products  and  issue  updates.  (All  changes  to  Xt  in  R4  are 
backwards  compatible  so  that  any  software  that  runs  under  R3  will  also  run  under  R4.) 

You  can  get  the  X  software  directly  from  MIT  on  three  9-track  1600  BPI  magtapes  written  in 
UNIX  tar  format  or  on  one  9-track  6250  BPI  magtape,  along  with  printed  copies  of  MIT's 
manuals,  by  sending  a  check  in  U.S.  currency  for  U.S.  $400  to: 

MIT  Software  Distribution  Center 

Technology  Licensing  Office 

MITE32-300 

77  Massachusetts  Avenue 

Cambridge,  MA  02139 

Their  telephone  number  is  (617)  253-6966,  and  the  "X  Ordering  Hotline"  is  (617)  258-8330. 
If  you  want  the  tapes  and  manuals  shipped  overseas,  the  price  is  $500.  The  manual  set  alone 
is  $125,  including  U.S.  shipping,  or  $175,  including  overseas  shipping. 

Other  distribution  media  or  formats  are  not  available  from  the  MIT  Software  Distribution 
Center,  but  are  from  other  independent  vendors  such  as  ICS,  mentioned  later.  The  Release 
tape  comes  with  source  code  for  sample  servers  for  Sun,  HP,  IBM,  Apollo,  Sony,  DEC  and 
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several  other  workstations,  source  code  for  clients  written  by  MIT,  sources  for  the  toolkits 
Xt,  XView  (in  R4),  Interviews,  and  Andrew,  contributed  software  written  outside  MIT,  and 
sources  and  postscript  files  for  all  MIT's  documentation.  Note  that  the  servers  supplied  are 
sample  servers  only;  commercial  vendors  typically  release  optimized  (faster)  servers  for  the 
same  machines. 

Sites  that  have  access  to  the  Internet  can  retrieve  the  distribution  from  the  following 
machines  using  anonymous  ftp.  Here  are  the  current  sites: 


Location 

Hostname 

Address 

Directory 

West 

gatekeeper.dec.com 

128.45.9.52 

publX.VllRS 

nic.mr.net 

192.12.250.5 

publX.VHR3 

East 

UUNET.uu.net 

192.12.141.129 

X/X.V11R3 

Northeast 

expo.lcs.mit.edu 

18.30.0.212 

publX.VUR3 

Midwest 

cygnusxl.cs.utk.edu 

128.169.201.12 

publX.VHR3 

giza.  cis.  ohio-state.  edu 

128.146.8.61 

publX.VHR3 

South 

dinorah.wustl.  edu 

129.252.118.101 

publX.VllR3 

DO  NOT  do  anonymous  ftp  during  normal  business  hours,  and  please  use  the  machine 
nearest  you. 

The  distribution  is  also  available  by  UUCP  from  UUNET,  for  sites  without  Internet  access. 
The  files  are  split  up  to  be  small  enough  for  UUCP  distribution. 


G.1.1    Bug  Fixes 


Critical  bug  fixes  as  well  as  a  limited  number  of  important  new  features  are  available  from 
the  archive  server  xstuff@expo.lcs.mit.edu.  Electronic  mail  sent  to  this  address  is  forwarded 
to  a  program  which  responds  with  the  requested  information.  The  rest  of  this  section  and  the 
two  that  follow  it  (entitled  Notes  and  Fairness)  explain  how  to  use  xstuffP. 

The  xstuff  server  is  a  mail-response  program.  This  means  that  you  mail  it  a  request,  and  it 
mails  back  the  response. 

The  xstuff  server  is  a  very  dumb  program.  It  does  not  have  much  error  checking.  If  you  don't 
send  it  commands  that  it  understands,  it  will  just  answer  "I  don't  understand  you." 

The  xstuff  server  reads  your  entire  message  before  it  does  anything,  so  you  can  have  several 
different  commands  in  a  single  message.  It  treats  the  "Subject:"  header  line  just  like  any 
other  line  of  the  message.  You  can  use  any  combination  of  upper  and  lower  case  letters  in 
the  commands. 

The  archives  are  organized  into  a  series  of  directories  and  subdirectories.  Each  directory  has 
an  index,  and  each  subdirectory  has  an  index.  The  top-level  index  gives  you  an  overview  of 
what  is  in  the  subdirectories,  and  the  index  for  each  subdirectory  tells  you  what  it  contains. 

If  you  are  bored  with  reading  documentation  and  just  want  to  try  something,  then  send  the 
server  a  message  containing  the  line: 
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send  index  fixes 


When  you  get  the  index  back,  it  will  contain  the  numbers  of  all  of  the  fixes  and  batches  of 
fixes  in  the  archive.  Then  you  can  send  the  server  another  message  asking  it  to  send  you  the 
fixes  that  you  want: 

send  fixes  159  11-20 

If  you  are  using  a  mailer  that  understands  "@"  notation,  send  to  xstujf@expo.lcs.mit.edu.  If 
your  mailer  deals  in  "!"  notation,  try  sending  to  {someplace}  teddie!  expo. Ics.mit.edu'xstuff. 
For  other  mailers,  you're  on  your  own. 

The  server  has  four  commands.  Each  command  must  be  the  first  word  on  a  line. 

help  The  command  help  or  send  help  causes  the  server  to  send  you  the  help  file.  No 
other  commands  are  honored  in  a  message  that  asks  for  help  (the  server  figures  that 
you  had  better  read  the  help  message  before  you  do  anything  else). 

index  If  your  message  contains  a  line  whose  first  word  is  index,  then  the  server  will  send 
you  the  top-level  index  of  the  contents  of  the  archive.  If  there  are  other  words  on 
that  line  that  match  the  name  of  subdirectories,  then  the  indexes  for  those  subdirec 
tories  are  sent  instead  of  the  top-level  index.  For  example,  you  can  say: 

index 
on 

index   fixes 

You  can  then  send  back  another  message  to  the  xstuff  server,  using  a  send  command 
(see  below)  to  ask  it  to  send  you  the  files  whose  name  you  learned  from  that  list. 

index  fixes  and  send  index  fixes  mean  the  same  thing:  you  can  use  send  instead  of 
index  for  getting  an  index. 

If  your  message  has  an  index  or  a  send  index  command,  then  all  other  send  com 
mands  will  be  ignored.  This  means  that  you  cannot  get  an  index  and  data  in  the 
same  request  This  is  so  that  index  requests  can  be  given  high  priority. 

send  If  your  message  contains  a  line  whose  first  word  is  send,  then  the  xstuff  server  will 
send  you  the  item(s)  named  on  the  rest  of  the  line.  To  name  an  item,  you  give  its 
directory  and  its  name.  For  example: 

send   fixes    1-10 

Once  you  have  named  a  category,  you  can  put  as  many  names  as  you  like  on  the 
rest  of  the  line.  They  will  all  be  taken  from  that  category.  For  example: 

send  fixes  1-10  11-20  21-30 

Each  send  command  can  reference  only  one  directory.  If  you  would  like  to  get  one 
fix  and  one  of  something  else,  you  must  use  two  send  commands. 

You  may  put  as  many  send  commands  as  you  like  into  one  message  to  the  server, 
but  the  more  you  ask  for,  the  longer  it  will  take  to  receive.  See  the  Fairness  Section 
below,  for  an  explanation.  Actually,  it's  not  strictly  true  that  you  can  put  as  many 
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send  commands  as  you  want  into  one  message.  If  the  server  must  use  UUCP  mail  to 
send  your  files,  then  it  cannot  send  more  than  100K  bytes  in  one  message.  If  you 
ask  for  more  than  it  can  send,  then  it  will  send  as  much  as  it  can  and  ignore  the  rest 

path         The  path  command  exists  to  help  in  case  you  do  not  get  responses  from  the  server 
when  you  mail  to  it 

Sometimes  the  server  is  unable  to  return  mail  over  the  incoming  path.  There  are 
dozens  of  reasons  why  this  might  happen,  and  if  you  are  a  true  wizard,  you  already 
know  what  those  reasons  are.  If  you  are  an  apprentice  wizard,  you  might  not  know 
all  the  reasons,  but  you  might  know  a  way  to  circumvent  them. 

If  you  put  in  a  path  command,  then  everything  that  the  server  mails  to  you  will  be 
mailed  to  that  address,  rather  than  to  the  return  address  on  your  mail.  The  server 
host  expo.lcs.mit.edu  does  not  have  a  direct  UUCP  connection  to  anywhere;  you 
must  go  through  mit-eddie  (the  UUCP  name  of  eddie.mit.edu)  or  somewhere  else. 


G.  1.1.1     Notes 


The  xstuff  server  acknowledges  every  request  by  return  mail.  If  you  don't  get  a  message 
back  in  a  day  or  two  you  should  assume  that  something  is  going  wrong,  and  perhaps  try  a 
path  command. 

The  xstuff  server  does  not  respond  to  requests  from  users  named  root,  system,  daemon,  or 
mailer.  This  is  to  prevent  mail  loops.  If  your  name  is  "Bruce  Root"  or  "Jane  Daemon",  and 
you  can  document  this,  I  will  happily  rewrite  the  server  to  remove  this  restriction.  Yes,  I 
know  about  Norman  Mailer  and  Waverley  Root.  Norman  doesn't  use  netmail  and  Waverley 
is  dead. 


G.1.1.2    Fairness 


The  xstuff  server  contains  many  safeguards  to  ensure  that  it  is  not  monopolized  by  people 
asking  for  large  amounts  of  data.  The  mailer  is  set  up  so  that  it  will  send  no  more  than  a  fixed 
amount  of  data  each  day.  If  the  work  queue  contains  more  requests  than  the  day's  quota,  then 
the  unsent  files  will  not  be  processed  until  the  next  day.  Whenever  the  mailer  is  run  to  send 
its  day's  quota,  it  sends  the  requests  out  shortest-first 

If  you  have  a  request  waiting  in  the  work  queue  and  you  send  in  another  request,  the  new 
request  is  added  to  the  old  one  (thereby  increasing  its  size)  rather  than  being  filed  anew.  This 
prevents  you  from  being  able  to  send  in  a  large  number  of  small  requests  as  a  way  of  beating 
the  system. 

The  reason  for  all  of  these  quotas  and  limitations  is  that  the  delivery  resources  are  finite,  and 
there  are  many  people  who  would  like  to  make  use  of  the  archive. 
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G.2  Netnews 


The  Usenet  network  news  is  probably  the  most  valuable  source  of  information  about  X.  The 
current  list  of  public  news  groups  that  discuss  X  is  as  follows: 


News  Group 


xll-3D 

x-ada 

xfont 

ximage 

xnonfb 

xpc 

xpert 

xserial 

xtensions 

xvideo 


Description 


People  interested  in  X  and  3-D  graphics 

Xandada 

People  interested  in  fonts 

People  interested  in  image  processing  and  X 

Server  implementors  for  non-frame  buffers 

People  interested  in  implementing  X  on  PCs 

General  discussion  of  X 

Serial  line  X  servers 

Technical  discussion  of  changes  to  X 

Discussion  of  video  extensions  for  X 


The  developers  of  X  post  notices  of  fixes  to  the  software  to  comp.windowjc,  and  this  is  where 
users  and  developers  around  the  world  ask  and  answer  questions. 


G.3  Training  and  Consulting 


Numerous  independent  vendors  provide  courses  on  X  programming.  Several  sources  that  we 
are  aware  of  include: 

•  Integrated  Computer  Solutions,  163  Harvard  Street,  Cambridge,  MA  02139;  (617) 
547-0510.  Courses  on  Xlib,  Motif,  strategic  overviews  of  X.  Also  provides  consulting 
services  and  manages  an  X  user's  group. 

•  Hands-On  Learning,  27  Cambridge  Street,  Burlington,  MA  01803;  (617)  272-0088. 
Courses  on  Xlib  and  Xt. 

•  X  tutorials  are  now  a  regular  feature  of  UNIX  conventions  such  as  the  UNIX  EXPO, 
Usenix,  Uniforum,  the  annual  X  conference  at  MIT,  and  Xhibition,  the  conference  organ 
ized  by  ICS.  Also  contact  commercial  server  vendors  for  information  on  courses  they 
offer. 

Training  companies  wishing  to  be  listed  here  should  send  us  information  on  the  courses  they 
offer. 
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G.3.1    Phone  Support 

X  programming  is  a  very  new  field,  and  since  everyone  who  knows  enough  to  help  you  is 
overworked,  you  are  likely  to  hear  "you're  on  your  own"  if  you  try  to  call  for  help.  There  are 
currently  no  support  lines,  because  X  was  developed  by  a  university,  not  a  system  manufac 
turer  or  software  house.  When  X  becomes  widely  supported  as  a  commercial  product,  the  sit 
uation  will  change  as  vendors  offer  support. 

ICS  provides  phone  support  for  a  fee.  See  Section  G.3  for  their  telephone  number. 


G.4  The  X  Consortium 


The  X  Consortium  can  be  reached  at: 

MIT  X  Consortium 

545  Technology  Square  Rm.  217 

Cambridge,  MA  02 139 

The  consortium's  phone  number  is  (617)  253-8861;  its  current  members  are  shown  below. 


ACER  Counterpoint,  Inc. 

AT&T 

Adobe  Systems 

Advanced  Graphics  Engineering 

Apollo  Computer,  Inc. 

Apple  Computer,  Inc. 

Ardent  Computer 

BULLMTS 

CETIA 

CalComp 

Canterbury  University,  England 

Carnegie  Mellon  University 

Codonics,  Inc. 

Control  Data  Corporation 

Cray  Research,  Inc. 

Data  General 

Digital  Equipment  Corp. 

Eastman  Kodak  Company 

Evans  &  Sutherland 

Fujitsu  America,  Inc. 

GfxBase 

Hewlett-Packard  Company 

IBM  Corporation 

INESC* 

Integrated  Computer  Solutions,  Inc. 

Integrated  Solutions,  Inc. 


Matrox  International 

Megatek  Corp. 

Mitsubishi  Electric  Corporation 

NCR  Corporation 

NEC  Corporation 

NTT  Corporation 

Network  Computing  Devices,  Inc. 

Nova  Graphics  International 

O'Reilly  &  Associates,  Inc. 

OMRON  Tateisi  Electronics 

Open  Software  Foundation 

PCS  Computer  Systeme  GmbH 

Prime  Computer,  Inc. 

Reuters 

Samsung  Software  America 

Sequent  Computer  Systems  Inc. 

Siemens  AG 

Silicon  Graphics  Computer  Systems 

Societe  de  Gestion  et  d'Informatique  Publicis 

Software  Productivity  Consortium 

Solboume  Computer  Inc. 

Sony  Corporation 

Stanford  University 

Stellar  Computer  Inc. 

Sun  Microsystems,  Inc. 

Tatung  Science  and  Technology 


*  Institute  de  Engenharia  de  Sistemas  e  Computadorcs 
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Interactive  Development  Environments      Tektronix,  Inc. 

Interactive  Systems  Corp.  Texas  Instruments 

Jupiter  Systems  UNICAD,  Inc. 

Key  Systems  Engineering  Corp.  Unisys  Corp. 

Landmark  Graphics  Corp.  University  of  Lowell 

Locus  Computing  Corp.  Visual  Technology,  Inc. 

MIPS  Computer  Systems  Wang  Laboratories 

MITRE  Corp.  X/Open  Company  Ltd. 

Most  of  these  companies  are  preparing  products  based  on  X.  It  should  not  be  long  before 
many  different  products  are  available  that  support  X. 


G.5  Finding  Out  for  Yourself 

X  is  unusual  in  that  the  source  code  is  in  the  public  domain.  It  should  be  possible  for  most  X 
programmers  to  get  a  copy  of  the  X  source  code  from  the  sources  listed  above.  Once  you 
understand  how  the  code  is  organized,  you  can  look  up  certain  details  about  how  X  works  as 
long  as  you  have  a  good  knowledge  of  C  and  a  little  persistence.  In  "Star  Wars,"  the  saying 
was  "Use  the  Force,  Luke."  In  X,  it  is  "Use  the  Source,  Luke." 

Xlib  and  the  server  are  two  distinct  chunks  of  code.  Each  contains  code  for  sending  and 
receiving  information  to  and  from  the  other  over  the  network  using  protocol  requests,  replies, 
events,  and  errors.  The  source  tree  as  supplied  on  the  X  distribution  tape  places  the  Xlib 
source  in  the  directory  baselliblX,  where  base  is  the  top  of  the  entire  source  tree.  Their  server 
source  is  placed  in  base/server. 

The  procedure  for  finding  out  something  about  an  Xlib  routine  is  normally  to  search  for  the 
routine  in  the  Xlib  code,  and  then  figure  out  what  it  does.  Sometimes  the  answer  can  be 
found  there.  Many  of  the  routines,  however,  simply  place  their  arguments  in  a  protocol 
request  and  send  it  to  the  server.  Then  you  will  have  to  look  in  the  server  code  for  the 
answer.  To  find  the  correct  place  in  the  server  code,  you  will  need  the  symbol  for  the  proto 
col  request,  which  is  the  first  argument  in  the  GetReq  call. 

The  server  code  is  much  more  involved  than  Xlib  itself.  The  device-dependent  portions  are 
in  basel  server  I  ddx  and  the  device-independent  portions  are  in  base/ server /dix.  The  device- 
independent  code  should  be  your  first  stop,  because  it  is  here  that  protocol  requests  from  Xlib 
arrive  and  are  dispatched  to  the  appropriate  code.  Search  for  the  protocol  request  symbol 
you  found  in  Xlib.  It  will  appear  in  several  source  files.  Start  with  the  occurrence  in  dis- 
patch.c,  and  try  to  figure  out  what  the  code  does.  This  will  require  following  leads  to  other 
routines. 

If  you  don't  find  a  routine  in  basel  server  I  dix,  then  it  must  be  in  the  device-dependent  code. 
basel  server  I  ddx  has  one  directory  in  it  for  each  brand  of  hardware  to  which  a  sample  server 
has  been  ported.  It  also  contains  the  directories  /mi,  Icfb,  Imfb,  and  Isnf,  which  contain  rou 
tines  used  in  writing  the  sample  server  device-dependent  code.  Note  that  servers  may 
include  code  ostensibly  for  other  machines.  For  example,  the  Sun  sample  server  appears  to 
use  code  in  several  of  the  directories  for  other  servers  such  as  dec  and  hp. 
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X  uses  many  common  terms  in  unique  ways.  A  good  example  is  "children." 
While  most,  if  not  all,  of  these  terms  are  defined  where  they  are  first  used  in 
this  manual,  you  will  undoubtedly  find  it  easier  to  refresh  your  memory  by 
looking  for  them  here. 
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This  glossary  is  an  expanded  version  of  the  glossary  from  Volume  One,  Xlib  Programming 
Manual  (which  in  turn  is  based  on  the  glossary  in  the  Xlib-C  Language  X Interface,  by  Jim 
Gettys,  Ron  Newman,  and  Bob  Scheifler).  As  such,  it  contains  definitions  of  many  Xlib  terms 
not  actually  used  in  this  book,  but  which  you  might  come  across  in  other  reading,  or  in  com 
ments  in  code.  In  some  cases,  these  Xlib  terms  may  be  used  in  the  definitions  of  the  Xt  terms 
given  in  this  glossary.  Any  term  used  in  a  definition,  for  which  another  entry  exists  in  the 
glossary,  is  generally  shown  in  italics. 

accelerator 

An  accelerator  is  a  translation  that  maps  events  in  one  widget  to  actions  in  an 
other.  The  name  is  based  on  the  most  frequent  use  for  this  feature,  namely  to  pro 
vide  keyboard  shortcuts  to  invoke  application  or  widget  functions  that  would  other 
wise  have  only  a  pointer-driven  interface. 

accept_focus  method 

The  accept  Jocus  method  of  a  child  is  invoked  when  a  parent  offers  the  keyboard 
focus  to  a  child  by  calling  XtCallAcceptFocus.  This  method  is  part  of  the 
Core  widget  class. 

access  control  list 

X  maintains  lists  of  hosts  that  are  allowed  access  to  each  server  controlling  a  dis 
play.  By  default,  only  the  local  host  may  use  the  display,  plus  any  hosts  specified 
in  the  access  control  list  for  that  display.  This  access  control  list  can  be  changed 
by  clients  on  the  local  host  Some  server  implementations  may  implement  other 
authorization  mechanisms  in  addition  to  or  instead  of  this  one.  The  list  can  cur 
rently  be  found  in  /etc/Xff.  hosts  where  #  is  the  number  of  the  display,  usually  0 
(zero).  The  access  control  list  is  also  known  as  the  host  access  list. 

action 

An  action  is  a  function  bound  by  a  translation,  to  be  invoked  in  response  to  a  user 
event 

actions  table 

An  actions  table  is  an  array  of  function  pointers  and  corresponding  strings  by 
which  actions  can  be  referenced  in  a  translation  table.  The  use  of  actions  requires 
a  widget  to  define  both  an  actions  table  and  a  translation  table. 
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active  grab 

A  grab  is  active  when  the  pointer  or  keyboard  is  actually  owned  by  a  single  grab 
bing  client.  See  also  graft. 

ancestor 

If  window  W  is  an  inferior  of  window  A,  then  A  is  an  ancestor  of  W.  The  parent 
window,  the  parent's  parent  window,  and  so  on  are  all  ancestors  of  the  given  win 
dow.  The  root  window  is  the  ancestor  of  all  windows  on  a  given  screen. 

application  context 

An  application  context  specifies  a  connection  to  a  server.  When  an  application 
program  has  connections  to  multiple  servers,  the  application  context  coordinates 
events  and  their  dispatching,  so  all  connections  get  processed. 

argument  list 

An  argument  list  is  used  in  a  call  to  create  a  widget  in  order  to  "hardcode"  the  val 
ue  of  widget  resources,  and  also  in  calls  to  xt  Set  Values  or  xtGetValues.  It 
consists  of  an  array  of  Arg  structures,  each  consisting  of  a  resource  name  and  the 
value  to  which  it  should  be  set 

Athena  widget 

MIT  distributes  a  set  of  widgets  developed  by  MIT's  Project  Athena  in  the  Athena 
Widget  library,  Xaw.  The  include  files  for  Athena  widgets  reside  in 
lusrlincludelXll  under  Release  3  and  usr/include/Xll/Xaw  under  Release  4. 

atom 

An  atom  is  a  unique  numeric  ID  corresponding  to  a  string  name.  Atoms  are  used  to 
identify  properties,  types,  and  selections  in  order  to  avoid  the  overhead  of  passing 
arbitrary-length  strings  over  the  network.  See  also  property. 

background 

Windows  may  have  a  background,  consisting  of  either  a  solid  color  or  a  tile  pat 
tern.  If  a  window  has  a  background,  it  will  be  repainted  automatically  by  the 
server  whenever  there  is  an  Expose  event  on  the  window.  If  a  window  does  not 
have  a  background,  it  will  be  transparent.  By  default,  a  window  has  a  background. 
See  also  foreground. 

backing  store 

When  a  server  maintains,  the  contents  of  a  window,  the  off-screen  saved  pixels  are 
known  as  a  backing  store.  This  feature  is  not  available  on  all  servers.  Even  when 
available,  the  server  will  not  maintain  a  backing  store,  unless  told  to  do  so  with  a 
window  attribute.  Use  the  DoesBackingStores  Xlib  macro  to  determine  if 
this  feature  is  supported. 
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bit  gravity 

When  a  window  is  resized,  the  contents  of  the  window  are  not  necessarily  discard 
ed.  It  is  possible  to  request  the  server  (though  no  guarantees  are  made)  to  relocate 
the  previous  contents  to  some  region  of  the  resized  window.  This  attraction  of  win 
dow  contents  for  some  location  of  a  window  is  known  as  bit  gravity.  For  example, 
an  application  that  draws  a  graph  might  request  that  the  contents  be  moved  into  the 
lower-left  corner,  so  that  the  origin  of  the  graph  will  still  appear  in  the  lower-left 
corner.  See  also  window  gravity. 

bit  plane 

On  a  color  or  gray  scale  display,  each  pixel  has  more  than  one  bit  defined.  Data  in 
display  memory  can  be  thought  of  either  as  pixels  (multiple  bits  per  pixel)  or  as  bit 
planes  (one  bit  plane  for  each  usable  bit  in  the  pixel).  The  bit  plane  is  an  array  of 
bits  the  size  of  the  screen. 

bitmap 

A  bitmap  is  a  pixmap  with  a  depth  of  one  bit.  There  is  no  bitmap  type  in  XI 1.  In 
stead,  use  a  pixmap  of  depth  1.  See  also  pixmap. 

border 

A  window  can  have  a  border  that  is  zero  or  more  pixels  wide.  If  a  window  has  a 
border,  the  border  can  have  a  solid  color  or  a  tile  pattern,  and  it  will  be  repainted 
automatically  by  the  server  whenever  its  color  or  pattern  is  changed  or  an  Expose 
event  occurs  on  the  window. 

button  grabbing 

A  pointer  grab  that  becomes  active  only  when  a  specified  set  of  keys  and/or  buttons 
are  held  down  in  a  particular  window  is  referred  to  as  a  button  grab. 

byte  order 

The  order  in  which  bytes  of  data  are  stored  in  memory  is  hardware-dependent.  For 
pixmaps  and  bitmaps,  byte  order  is  defined  by  the  server,  and  clients  with  different 
native  byte  ordering  must  swap  bytes  as  necessary.  For  all  other  parts  of  the  proto 
col,  the  byte  order  is  defined  by  the  client,  and  the  server  swaps  bytes  as  necessary. 

callback 

A  callback  is  an  application  function  registered  with  a  widget  by  the  application 
using  either  of  the  calls  XtAddCallback  or  XtAddCallbacks  or  through  an 
argument  list.  A  widget  declares  one  or  more  callback  lists  as  resources;  applica 
tions  add  functions  to  these  lists  in  order  to  link  widgets  to  applications  code. 

change_managed  method 

When  a  parent  should  change  its  managed  widgets,  the  change  jnanaged  method  is 
invoked,  at  which  time  a  parent  reorganizes  its  children.  The  change_managed 
method  is  part  of  the  Composite  widget  class. 
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child,  children 

1)  A  widget  created  by  xtCreateWidget  is  a  child  of  the  widget  specified  as 
its  parent.  The  parent  controls  the  layout  of  its  children. 

2)  The  children  of  a  window  are  its  first-level  subwindows.  All  of  these  windows 
were  created  with  the  same  window  as  parent  A  client  creates  its  top-level  win 
dow  as  a  child  of  the  root  window. 

class 

1)  (X  Toolkit)  A  widget's  class  determines  what  methods  will  be  called  for  it  and 
what  instance  variables  it  has.  For  widget  users,  a  widget's  class  is  declared  in  the 
.h  file  for  the  widget. 

2)  (Xlib)  There  are  two  uses  of  the  term  class  in  X:  window  class  and  visual  class. 
The  window  class  specifies  whether  a  window  is  inputOnly  or  Input- 
Output.  The  visual  class  specifies  the  color  model  that  is  used  by  a  window.  See 
the  classes  DirectColor,  Grayscale,  Pseudocolor,  StaticColor, 
StaticGray,  and  TrueColor.  Both  window  class  and  visual  class  are  set  per 
manently  when  a  window  is  created. 

class_initialize  method 

This  method — part  of  the  Core  widget — is  invoked  when  a  widget  class  is  initial 
ized.  That  is,  it  is  called  when  the  first  instance  of  a  particular  class  is  created. 

client 

An  application  program  connects  to  the  window  system  server  by  an  interprocess 
communication  (IPC)  path,  such  as  a  TCP  connection  or  a  shared  memory  buffer. 
This  program  is  referred  to  as  a  client  of  the  window  system  server.  More  precise 
ly,  the  client  is  the  IPC  path  itself;  a  program  with  multiple  paths  open  to  one  or 
more  servers  is  viewed  by  the  protocol  as  multiple  clients.  X  Resources  are  avail 
able  only  as  long  as  the  connection  remains  intact,  not  as  long  as  a  program  re 
mains  running.  Normally  the  connection  and  the  program  terminate  concurrently, 
but  the  client's  resources  may  live  on  if  XChangeCloseDownMode  has  been 
called. 

clipping  region 

In  many  graphics  routines,  a  bitmap  or  list  of  rectangles  can  be  specified  to  restrict 
output  to  a  particular  region  of  the  window.  The  image  defined  by  the  bitmap  or 
rectangles  is  called  a  clipping  region,  or  clip  mask.  Output  to  child  windows  is 
automatically  clipped  to  the  borders  of  the  parent  unless  subwindow_mode  of 
the  GC  is  Include  Inferiors.  Therefore  the  borders  of  the  parent  can  be 
thought  of  as  a  clipping  region. 

colorcell 

An  entry  in  a  colormap  is  known  as  a  colorcell.  An  entry  contains  three  values 
specifying  red,  green,  and  blue  intensities.  These  values  are  always  16-bit  un 
signed  numbers,  with  zero  being  minimum  intensity.  The  values  are  truncated  or 
scaled  by  the  server  to  match  the  display  hardware.  See  also  colormap. 
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colormap 

A  colormap  consists  of  a  set  of  colorcells.  A  pixel  value  indexes  into  the  colormap 
to  produce  intensities  of  Red,  Green,  and  Blue  to  be  displayed.  Depending  on 
hardware  limitations,  one  or  more  colormaps  may  be  installed  at  one  time,  such 
that  windows  associated  with  those  maps  display  with  true  colors.  Regardless  of 
the  number  of  installable  colormaps,  any  number  of  virtual  colormaps  can  be  creat 
ed.  When  needed,  a  virtual  colormap  can  be  installed  and  the  existing  installed 
colormap  might  have  to  be  uninstalled.  The  colormap  on  most  systems  is  a  limited 
resource  that  should  be  conserved  by  allocating  read-only  colorcells  whenever  pos 
sible,  and  by  selecting  RGB  values  from  the  predefined  color  database.  Read-only 
cells  may  be  shared  between  clients.  See  also  colorcell,  DirectColor,  Gray- 
Scale,  Pseudocolor,  StaticColor,  StaticGray,  and  TrueColor. 

Composite  widget 

A  Composite  widget  is  designed  to  manage  the  geometry  of  children;  that  is,  a 
Composite  widget  instance  can  be  passed  in  the  parent  argument  to  xtCreate- 
Widget. 

connection 

The  communication  path  between  the  server  and  the  client  is  known  as  a 
connection.  A  client  usually  (but  not  necessarily)  has  only  one  connection  to  the 
server  over  which  requests  and  events  are  sent. 

Constraint  widget 

The  Constraint  widget  is  a  subclass  of  Composite.  A  Constraint  widget  has  more 
information  about  each  child  than  a  Composite  widget 

constraints 

A  Constraint  widget  provides  a  list  of  resources,  or  constraints,  for  its  children. 
The  constraints  give  the  Constraint  widget  information  about  how  each  child 
should  be  layed  out 

containment 

A  window  contains  the  pointer  if  the  window  is  viewable  and  if  the  hotspot  of  the 
cursor  is  within  a  visible  region  of  the  window  or  a  visible  region  of  one  of  its  infe 
riors.  The  border  of  the  window  is  included  as  part  of  the  window  for  containment. 
The  pointer  is  in  a  window  if  the  window  contains  the  pointer  but  no  inferior  con 
tains  the  pointer. 

coordinate  system 

The  coordinate  system  has  x  horizontal  and  y  vertical,  with  the  origin  (0,  0)  at  the 
upper-left  Coordinates  are  discrete,  and  in  terms  of  pixels.  Each  window  and  pix- 
map  has  its  own  coordinate  system.  For  a  window,  the  origin  is  inside  the  border,  if 
there  is  one.  The  position  of  a  child  window  is  measured  from  the  origin  of  the  par 
ent  to  the  outside  corner  of  the  child  (not  the  child's  origin). 

Core  widget 

The  Core  widget  is  the  basic  class  in  the  Toolkit  All  widgets  that  can  be  displayed 
are  subclasses  of  Core. 
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cursor 

A  cursor  is  the  visible  shape  of  the  pointer  on  a  screen.  It  consists  of  a  hotspot,  a 
shape  bitmap,  a  mask  bitmap,  and  a  pair  of  pixel  values.  The  cursor  defined  for  a 
window  controls  the  visible  appearance  of  the  pointer  when  the  pointer  is  in  that 
window. 

delete_child  method 

The  delete_child  method  is  invoked  on  a  parent  after  its  child  is  deleted.  This 
method  is  part  of  the  Composite  widget  and  is  usually  inherited. 

depth 

The  depth  of  a  window  or  pixmap  is  the  number  of  bits  per  pixel. 

dereference 

To  access  the  contents  of  a  pointer,  you  must  dereference  it 

descendants 

See  inferiors. 

destroy  method 

The  destroy  method  is  invoked  when  a  widget  has  been  destroyed.  This  method  is 
part  of  the  Core  widget  and  is  used  to  deallocate  memory  and  GCs. 

device 

Keyboards,  mice,  tablets,  track-balls,  button  boxes,  etc.  are  all  collectively  known 
as  input  devices. 

DirectCoIor 

DirectColor  is  a  visual  class  in  which  a  pixel  value  is  decomposed  into  three  sepa 
rate  subfields  for  colormap  indexing.  One  subfield  indexes  an  array  to  produce  red 
intensity  values;  the  second  subfield  indexes  a  second  array  to  produce  blue  inten 
sity  values;  and  the  third  subfield  indexes  a  third  array  to  produce  green  intensity 
values.  The  RGB  (red,  green,  and  blue)  values  in  the  colormap  entry  can  be 
changed  dynamically.  This  visual  class  is  normally  found  on  high-performance 
color  workstations. 

display 

A  display  is  a  set  of  one  or  more  screens  that  are  driven  by  a  single  X  server.  The 
Xlib  Display  structure  contains  all  information  about  the  particular  display  and 
its  screens  as  well  as  the  state  that  Xlib  needs  to  communicate  with  the  display  over 
a  particular  connection.  In  Xlib,  a  pointer  to  a  Display  Structure  is  returned  by 
XOpenDisplay.  In  most  Xt  applications,  the  Display  is  part  of  the  applica 
tion  context,  and  need  not  be  referenced  directly.  If  necessary,  a  display  can  be 
opened  directly  with  a  call  to  xtOpenDisplay,  and  a  pointer  to  the  currently 
open  display  can  be  returned  by  the  xt Display  macro. 

drawable 

Both  windows  and  pixmaps  may  be  used  as  destinations  in  graphics  operations. 
These  are  collectively  known  as  drawables. 
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encapsulation 

Encapsulation  is  a  key  concept  in  object-oriented  programming.  Objects  are  de 
fined  in  such  a  way  that  their  internals  are  hidden  from  the  programs  that  use  them; 
the  only  way  to  access  an  object  should  be  through  its  published  interfaces. 

event 

An  X  event  is  a  data  structure  sent  by  the  server  that  describes  something  that  just 
happened  that  may  be  of  interest  to  the  application.  There  are  two  major  categories 
of  events:  user  input  and  window  system  side  effects.  For  example,  the  user  press 
ing  a  keyboard  key  or  clicking  a  mouse  button  generates  an  event;  a  window  being 
moved  on  the  screen  also  generates  events — possibly  in  other  applications  as  well 
if  the  movement  changes  the  visible  portions  of  their  windows.  It  is  the  server's 
job  to  distribute  events  to  the  various  windows  on  the  screen. 

event  compression 

Event  compression  is  an  Xt  feature  that  allows  some  events  to  be  ignored  or 
repackaged  before  they  are  given  to  a  widget  This  happens  on  the  client  side,  rath 
er  than  in  the  server. 

event  handler 

An  event  handler  is  a  function  that  is  called  by  Xt  when  a  particular  event  is  re 
ceived.  Event  handlers  have  the  same  purpose  as  translations  and  actions — to  call 
a  function  in  response  to  an  event — but  event  handlers  have  lower  overhead  and 
are  not  user-configurable. 

event  mask 

Events  are  requested  relative  to  a  window  or  widget  The  set  of  event  types  a  client 
requests  relative  to  a  window  is  described  using  an  event  mask,  a  bitwise  OR  of  de 
fined  symbols  specifying  which  events  are  desired. 

The  event_mask  is  a  window  attribute,  which  can  be  set  in  Xlib  with 
XSelect Input,  and  is  also  specified  in  calls  that  grab  the  pointer  or  keyboard. 
The  do_not_propagate_mask  attribute  is  also  an  event  mask,  and  it  speci 
fies  which  events  should  not  be  propagated  to  ancestor  windows.  In  Xt,  you  never 
need  to  set  a  window's  event_mask  or  do_not_propogate_mask  directly. 
The  translation  manager  automatically  selects  the  required  events. 

event  propagation 

Device-related  events  propagate  from  the  source  window  to  ancestor  windows  un 
til  a  window  that  has  selected  that  type  of  event  is  reached,  or  until  the  event  is  dis 
carded  explicitly  in  a  do_not_propagate_mask  attribute. 

event  source 

The  smallest  window  containing  the  pointer  is  the  source  of  a  device-related  event 

expose  method 

When  Expose  events  are  received,  the  Intrinsics  invoke  the  expose  method.  A 
widget  should  perform  its  redisplay  activities  in  this  method.  The  expose  meth 
od  is  part  of  the  Core  widget  class. 
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exposure 

Window  exposure  occurs  when  a  window  is  first  mapped,  or  when  another  window 
that  obscures  it  is  unmapped,  resized,  or  moved.  Servers  do  not  guarantee  to  pre 
serve  the  contents  of  windows  when  windows  are  obscured  or  reconfigured.  Ex 
pose  events  are  sent  to  clients  to  inform  them  when  contents  of  regions  of  win 
dows  have  been  lost  and  need  to  be  regenerated. 

extension 

Named  extensions  to  the  core  protocol  can  be  defined  to  extend  the  system.  Exten 
sion  to  output  requests,  resources,  and  event  types  are  all  possible,  and  expected. 
Extensions  can  perform  at  the  same  level  as  the  core  Xlib. 

font 

A  font  is  an  array  of  characters  or  other  bitmap  shapes  such  as  cursors.  The  proto 
col  does  no  translation  or  interpretation  of  character  sets.  The  client  simply  indi 
cates  values  used  to  index  the  font  array.  A  font  contains  additional  metric  infor 
mation  to  determine  intercharacter  and  interline  spacing. 

foreground 

The  pixel  value  that  will  actually  be  used  for  drawing  pictures  or  text  is  referred  to 
as  the  foreground.  The  foreground  is  specified  as  a  member  of  a  graphics  context. 
See  also  background. 

frozen  events 

Clients  can  freeze  event  processing  while  they  change  the  screen,  by  grabbing  the 
keyboard  or  pointer  with  a  certain  mode.  These  events  are  queued  in  the  server 
(not  in  Xlib)  until  an  XAllowEvents  call  with  a  counteracting  mode  is  given. 

GC 

The  term  GC  is  used  as  a  shorthand  for  graphics  context.  See  graphics  context. 

geometry  management 

A  Composite  parent  controls  its  children  through  geometry  management,  thereby 
manipulating  the  size  and  placement  of  widgets  within  a  window  on  the  display. 

get_values_hook  method 

The  get_yalues_hook  method  is  invoked  by  the  Intrinsics  when  someone  calls  xt- 
Getvalues.  This  method  is  part  of  the  Core  widget  class.  Its  role  is  to  get  the 
resource  values  of  a  subpart  using  xtGetSubvalues. 

glyph 

A  glyph  is  an  image,  usually  of  a  character  in  a  font,  but  also  possibly  of  a  cursor 
shape  or  some  other  shape. 

grab 

Keyboard  keys,  the  keyboard,  pointer  buttons,  the  pointer,  and  the  server  can  be 
grabbed  for  exclusive  use  by  a  client,  usually  for  a  short  time  period.  In  general, 
these  facilities  help  implement  various  styles  of  user  interfaces.  Pop-up  widgets 
generally  make  a  passive  grab.  Server  grabs  are  generally  used  only  by  window 
managers. 
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graphics  context 

Various  information  for  interpreting  graphics  primitives  is  stored  in  a  graphics  con 
text  (GC),  such  as  foreground  pixel,  background  pixel,  line  width,  clipping  region, 
etc.  Everything  drawn  to  a  window  or  pixmap  is  modified  by  the  GC  used  in  the 
drawing  request 

graphics  primitive 

A  graphics  primitive  is  an  Xlib  call  that  sends  a  protocol  request  to  the  server,  in 
structing  the  server  to  draw  a  particular  shape  at  a  particular  position.  The  graphics 
context  specified  with  the  primitive  specifies  how  the  server  interprets  the  primi 
tive. 

gravity 

See  bit  gravity  and  window  gravity. 

GrayScale 

Grayscale  is  a  visual  class  in  which  the  red,  green,  and  blue  values  in  any  given 
colormap  entry  are  equal,  thus  producing  shades  of  gray.  The  gray  values  can  be 
changed  dynamically.  Grayscale  can  be  viewed  as  a  degenerate  case  of 
Pseudocolor. 

hint 

Certain  properties,  such  as  the  preferred  size  of  a  window,  are  referred  to  as  hints, 
since  the  window  manager  makes  no  guarantee  that  it  will  honor  them. 

host  access  list 

See  access  control  list. 

hotspot 

A  cursor  has  an  associated  hotspot  that  defines  the  point  in  the  cursor  which  corre 
sponds  to  the  coordinates  reported  for  the  pointer. 

identifier 

Each  server  resource  has  an  identifier  or  ID,  a  unique  value  that  clients  use  to  name 
the  resource.  Any  client  can  use  a  resource  if  it  knows  the  resource  ID. 

inferiors 

The  inferiors  of  a  window  are  all  of  the  subwindows  nested  below  it  the  children, 
the  children's  children,  etc.  The  term  descendants  is  a  synonym. 

inheritance  (single  vs.  multiple) 

Inheritance  is  the  ability  to  obtain  methods  from  a  superclass.  Multiple  inheri 
tance,  which  is  not  supported  by  Xt,  would  allow  a  class  to  obtain  methods  from 
multiple  unrelated  superclasses. 

initialize  method 

The  initialize  method  is  invoked  when  a  widget  is  created.  It  initializes  instance 
variables  and  checks  resource  values.  This  method  is  part  of  the  Core  widget  class. 
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initialize_hook  method 

The  initialize _hook  method  is  called  just  after  the  initialize  method,  and  is  respon 
sible  for  initializing  subpart  instance  variables  and  checking  subpart  resource  val 
ues.  This  method  is  part  of  the  Core  widget  class. 

input  focus 

See  keyboard  focus. 

InputOnly  window 

A  window  that  cannot  be  used  for  graphics  requests  is  called  an  InputOnly  window. 
InputOnly  windows  are  invisible  and  can  be  used  to  control  such  things  as  cur 
sors,  input  event  distribution,  and  grabbing.  InputOnly  windows  cannot  have 
inputOutput  windows  as  inferiors. 

InputOutput  window 

The  normal  kind  of  window  that  is  used  for  both  input  and  output  is  called  an 
InputOutput  window.  It  usually  has  a  background.  InputOutput  windows  can 
have  both  InputOutput  and  InputOnly  windows  as  inferiors. 

input  manager 

Control  over  keyboard  input  may  be  provided  by  an  input  manager  client.  This  job 
is  more  often  done  by  the  window  manager. 

insert  child  method 

A  widget's  insert  child  method  is  invoked  when  someone  specifies  it  as  a  parent  in 
an  xtCreateWidget  call.  This  method  is  part  of  the  Composite  widget  class. 
This  method  is  usually  inherited. 

instance 

An  instance  is  a  particular  widget  that  has  a  class.  An  instance  ID  is  returned  by 
XtCreateWidget. 

instantiate 

When  you  instantiate  a  class,  you  create  an  instance  of  it 

Intrinsics 

The  X  Toolkit  defines  functions  and  datatypes  called  Intrinsics. 

key  grabbing 

A  keyboard  grab  that  occurs  only  when  a  certain  key  or  key  combination  is  pressed 
is  called  a  key  grab.  This  is  analogous  to  button  grabbing.  Both  are  forms  of  pas 
sive  grabs. 

keyboard  focus 

The  keyboard  focus  is  the  window  that  receives  main  keyboard  input.  By  default 
the  focus  is  the  root  window,  which  has  the  effect  of  sending  input  to  the  window 
that  is  being  pointed  to  by  the  mouse.  It  is  possible  to  attach  the  keyboard  input  to 
a  specific  window  with  XSetlnputFocus.  Events  are  then  sent  to  the  window 
independent  of  the  pointer  position. 
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keyboard  grabbing 

All  keyboard  input  is  sent  to  a  specific  window  (or  client,  depending  on 
owner_e vents)  when  the  keyboard  is  grabbed.  This  is  analogous  to  mouse 
grabbing.  This  is  very  much  like  a  temporary  keyboard  focus  window. 

keycode 

A  keycode  is  a  code  in  the  range  8-255  inclusive  that  represents  a  physical  or  logi 
cal  key  on  the  keyboard.  The  mapping  between  keys  and  keycodes  cannot  be 
changed,  and  varies  between  servers.  A  list  of  keysyms  is  associated  with  each 
keycode.  Programs  should  use  keysyms  instead  of  keycodes  to  interpret  key 
events. 

keysym 

A  keysym  is  a  #def  ine'd  symbol  which  is  a  portable  representation  of  the  sym 
bol  on  the  cap  of  a  key.  Each  key  may  have  several  keysyms,  corresponding  to  the 
key  when  various  modifier  keys  are  pressed.  You  should  interpret  key  events  ac 
cording  to  the  keysym  returned  by  XLookupString  or  XLookupKeysym, 
since  this  translates  server-dependent  keycodes  into  portable  keysyms. 

listener 

A  listener  style  window  manager  sets  the  keyboard  focus  to  a  particular  window 
when  that  window  is  clicked  on  with  a  pointer  button.  This  is  the  window  manager 
style  used  with  the  Apple  Macintosh™.  This  style  is  also  referred  to  as  click-to- 
type. 

loose  binding 

A  loose  binding  refers  to  the  use  of  an  asterisk  (*)  wildcard  in  a  resource  specifica 
tion  to  indicate  that  the  specification  applies  to  zero  or  more  hierarchy  levels  of 
widget  instances  or  classes. 

mapping 

A  window  is  said  to  be  mapped  if  an  XMapWindow  or  XMapRaised  call  has 
been  performed  on  it  Unmapped  windows  are  never  viewable.  Mapping  makes  a 
window  eligible  for  display.  The  window  will  actually  be  displayed  if  the  follow 
ing  conditions  are  also  met* 

1)  All  its  ancestors  are  mapped. 

2)  It  is  not  obscured  by  siblings. 

3)  The  window  manager  has  processed  the  request,  if  for  a  top-level  window. 

message 

In  object-oriented  programming,  a  message  is  used  to  invoke  an  object's  methods. 
In  Xt,  you  can  think  of  the  Intrinsics  functions  used  to  create,  destroy,  and  set  re 
source  values  as  sending  messages  to  widget  classes. 

method 

A  method  is  a  function  internal  to  widget  class  that  the  Intrinsics  invoke  under 
specified  conditions.  Methods  are  provided  as  pointers  to  functions  in  widget  class 
records. 
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modal  pop  up 

A  modal  pop  up  is  a  pop-up  widget  that  grabs  the  pointer  when  a  mouse  button  is 
pressed  in  a  particular  window. 

modeless  pop  up 

A  modeless  pop  up  is  a  pop-up  widget  that  doesn't  grab  the  pointer  on  a  mouse  but 
ton. 

modifier  keys 

Shift,  Control,  Meta,  Super,  Hyper,  Alt,  Compose,  Apple,  Caps  Lock,  Shift  Lock, 
and  similar  keys  are  called  modifier  keys. 

monochrome 

A  monochrome  screen  has  only  two  colors:  black  and  white.  Monochrome  is  a 
special  case  of  the  StaticGray  visual  class,  in  which  there  are  only  two  color- 
map  entries. 

non-maskable  event 

A  non-maskable  event  is  an  event  that  is  not  selected  by  the  application  or  widget 
via  an  event  mask,  but  is  instead  sent  automatically  by  the  X  server.  The  non 
maskable  events  are  MappingNotify,  ClientMessage,  Selection- 
Clear,  SelectionNotify, and  SelectionRequest. 

object 

In  object-oriented  programming,  an  object  is  a  self-contained  program  unit  con 
taining  both  data  and  procedures. 

object-oriented  programming 

Object-oriented  programming  is  a  way  of  defining  classes  and  creating  instances 
so  that  objects  respond  to  messages  with  methods.  One  of  its  major  benefits  is  the 
encapsulation  of  code. 

obscure 

Window  A  obscures  window  B  if  A  is  higher  in  the  global  stacking  order,  and  the 
rectangle  defined  by  the  outside  edges  of  A  intersects  the  rectangle  defined  by  the 
outside  edges  of  B.  See  occlude. 

occlude 

Window  A  occludes  window  B  if  both  are  mapped,  if  A  is  higher  in  the  global 
stacking  order,  and  if  the  rectangle  defined  by  the  outside  edges  of  A  intersects  the 
rectangle  defined  by  the  outside  edges  of  B.  The  (fine)  distinction  between  the 
terms  obscures  and  occludes  is  that  for  obscures,  the  windows  have  to  be  mapped, 
while  for  occludes  they  don't.  Also  note  that  window  borders  are  included  in  the 
calculation.  Note  that  input  Only  windows  never  obscure  other  windows  but 
can  occlude  other  windows. 

padding 

Some  bytes  are  inserted  in  the  data  stream  to  maintain  alignment  of  the  protocol  re 
quests  on  natural  boundaries.  This  padding  increases  ease  of  portability  to  some 
machine  architectures. 
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parent 

A  parent  is  a  Composite  widget  instance  specified  as  the  parent  argument  in  xt- 
CreateWidget.  Parents  control  a  child's  layout 

parent  window 

Each  new  window  is  created  with  reference  to  another  previously-created  window. 
The  new  window  is  referred  to  as  the  child,  and  the  reference  window  as  the  par 
ent.  If  C  is  a  child  of  P,  then  P  is  the  parent  of  C.  Only  the  portion  of  the  child  that 
overlaps  the  parent  is  viewable. 

passive  grab 

A  passive  grab  is  a  grab  that  will  become  active  only  when  a  specific  key  or  button 
is  actually  pressed  in  a  particular  window. 

pixel  value 

A  pixel  value  is  an  N-bit  value,  where  N  is  the  number  of  bit  planes  used  in  a  par 
ticular  window  or  pixmap.  For  a  window,  a  pixel  value  indexes  a  colormap  to  de 
rive  an  actual  color  to  be  displayed.  For  a  pixmap,  a  pixel  value  will  be  interpreted 
as  a  color  in  the  same  way  when  it  has  been  copied  into  a  window. 

pixmap 

A  pixmap  is  a  three-dimensional  array  of  bits.  A  pixmap  is  normally  thought  of  as 
a  two-dimensional  array  of  pixels,  where  each  pixel  can  be  a  value  from  0  to 
(2N  -1),  where  N  is  the  depth  (z-axis)  of  the  pixmap.  A  pixmap  can  also  be  thought 
of  as  a  stack  of  N  bitmaps.  A  pixmap  may  have  only  one  plane.  Such  a  pixmap  is 
often  referred  to  as  a  bitmap,  even  though  there  is  no  bitmap  type  in  XI 1. 

plane 

When  a  pixmap  or  window  is  thought  of  as  a  stack  of  bitmaps,  each  bitmap  is 
called  a  plane. 

plane  mask 

Graphics  operations  can  be  restricted  to  affect  only  a  subset  of  bit  planes  in  a  draw- 
able.  A.  plane  mask  is  a  bit  mask  describing  which  planes  are  to  be  modified. 

pointer 

The  pointer  is  the  pointing  device  currently  attached  to  the  cursor,  and  tracked  on 
the  screens.  This  may  be  a  mouse,  tablet,  track-ball,  or  joystick. 

pointer  grabbing 

A  client  can  actively  grab  control  of  the  pointer,  causing  button  and  motion  events 
to  be  sent  to  that  client  rather  than  to  the  client  the  pointer  indicates. 

pointing  device 

A  pointing  device  is  typically  a  mouse  or  tablet,  or  some  other  device  with  effec 
tive  two-dimensional  motion,  that  usually  has  buttons.  There  is  only  one  visible 
cursor  defined  by  the  core  protocol,  and  it  tracks  whatever  pointing  device  is  cur 
rently  attached  as  the  pointer. 
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pop  up 

A  pop  up  is  a  widget  outside  the  normal  parental  hierarchy  of  geometry  manage 
ment  It  is  a  child  window  of  the  root  window  that  is  popped  up  temporarily  to 
give  the  user  a  piece  of  information,  or  to  get  some  information  from  the  user. 

post-order  traversal 

When  a  tree  structure  is  subject  to  post-order  traversal,  its  root  is  visited  last;  for 
example,  a  function  might  process  the  left  descendant,  the  right  descendant,  and 
then  the  root 

pre-order  traversal 

When  a  tree  structure  is  subject  to  pre-order  traversal,  its  root  is  visited  first;  for 
example,  a  function  might  process  the  root,  and  then  the  left  and  right  descendant 

private  header  file 

A  private  header  file  contains  the  internal  class  definitions  of  a  widget  For  ex 
ample,  the  Label  widget's  internal  class  definitions  are  contained  in  the  private 
header  file  LabelP.h.  This  file  is  included  only  in  the  widget  .c  file  of  this  class  and 
any  subclasses,  never  in  the  application. 

property 

Windows  may  have  associated  properties,  each  consisting  of  a  name,  a  type,  a  data 
format,  and  some  data.  The  protocol  places  no  interpretation  on  properties;  they 
are  intended  as  a  general-purpose  data  storage  and  intercommunication  mechanism 
for  clients.  There  is,  however,  a  list  of  predefined  properties  and  property  types  so 
that  clients  might  share  information  such  as  resize  hints,  program  names,  and  icon 
formats  with  a  window  manager  via  properties.  In  order  to  avoid  passing  arbitrary- 
length  property-name  strings,  each  property  name  is  associated  with  a  correspond 
ing  integer  value  known  as  an  atom.  See  also  atom. 

PseudoColor 

PseudoColor  is  a  visual  class  in  which  a  pixel  value  indexes  the  colormap  entry  to 
produce  independent  red,  green,  and  blue  values.  That  is,  the  colormap  is  viewed 
as  an  array  of  triples  (RGB  values).  The  RGB  values  can  be  changed  dynamically. 

public  header  file 

A  public  header  file  contains  the  declarations  (e.g.,  class  widget  pointer)  necessary 
to  use  a  widget  For  example,  labelwidgetClass  declarations  are  contained 
in  the  public  header  file  label.h.  This  header  file  is  included  in  the  widget  .c  file 
and  in  the  application  source  file. 

quark 

A  quark  is  an  integer  ID  that  identifies  a  string.  In  the  context  of  Xt,  this  string  is 
usually  a  name,  class,  or  type  string  for  the  resource  manager.  Like  atoms  and  re 
source  IDs,  quarks  eliminate  the  need  to  pass  strings  of  arbitrary  length  over  the 
network.  The  quark  type  is  XrmQuark,  and  the  types  XrmName,  XrmClass, 
and  XrmRepresentation  are  also  defined  to  be  XrmQuark. 
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query  geometry  method 

Parents  call  Xt  Query  Geometry  to  invoke  the  child's  query  geometry  method  to 
find  out  a  child's  preferred  geometry.  This  method  is  part  of  the  Core  widget  class. 

raise 

Changing  the  stacking  order  of  a  window  so  as  to  occlude  all  sibling  windows  is  to 
raise  that  window. 

real  estate 

The  window  management  style  characterized  by  the  input  being  sent  to  whichever 
window  the  pointer  is  in  is  called  real-estate-driven.  This  is  the  most  common 
style  of  input  management  used  in  X. 

realize  method 

The  realize  method  creates  a  window  on  the  display  and  is  part  of  the  Core  widget 
class. 

rectangle 

A  rectangle  specified  by  [x,y,w,h]  has  an  (infinitely  thin)  outline  path  with  cor 
ners  at  [x,y],  [x+w,y],  [x+w,y+h],  and  [x,y+h].  When  a  rectangle  is  filled, 
the  lower-right  edges  are  not  drawn.  For  example,  if  w=h=0,  nothing  would  be 
drawn  when  drawing  the  rectangle,  but  a  single  pixel  when  filling  it.  For  w=h=l,  a 
single  pixel  would  be  drawn  when  drawing  the  rectangle,  four  pixels  when  filling 
it 

redirect 

Window  managers  (or  other  clients)  may  wish  to  enforce  window  layout  policy  in 
various  ways.  When  a  client  attempts  to  change  the  size  or  position  of  a  window, 
or  to  map  one,  the  operation  may  be  redirected  to  the  window  manager,  rather  than 
actually  being  performed.  Then  the  window  manager  (or  other  client  that  redirect 
ed  the  input)  is  expected  to  decide  whether  to  allow,  modify,  or  deny  the  requested 
operation  before  making  the  call  itself.  See  also  window  manager. 

reparenting 

The  window  manager  often  reparents  the  top-level  windows  of  each  application  in 
order  to  add  a  tide  bar  and  perhaps  resize  boxes.  In  other  words,  a  window  with  a 
title  bar  is  inserted  between  the  root  window  and  each  top-level  window.  See  also 
save-set. 

reply 

Information  requested  from  the  server  by  a  client  is  sent  back  to  the  client  in  a 
reply.  Both  events  and  replies  are  multiplexed  on  the  same  connection  with  the  re 
quests.  Requests  that  require  replies  are  known  as  round-trip  requests,  and,  if  pos 
sible,  should  be  avoided  since  they  introduce  network  delays.  Most  requests  do  not 
generate  replies.  Some  requests  generate  multiple  replies.  Xt  caches  frequently- 
used  data  on  the  client  side  of  the  connection  in  order  to  minimize  the  need  for 
round-trip  requests.  See  Volume  Zero,  X  Protocol  Reference  Manual,  for  a  de 
tailed  discussion  of  the  X  protocol. 
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representation  type 

A  symbolic  constant  beginning  with  XtR,  which  is  defined  in  <Xll/StringDefs.h> 
or  an  application  or  widget  header  file,  and  which  is  used  to  define  the  data  type  of 
a  resource.  Xt  automatically  converts  between  resource  settings,  which  are  strings, 
and  various  representation  types. 

request 

A  command  to  the  server  is  called  a  request.  It  is  a  single  block  of  data  sent  over 
the  connection  to  the  server.  See  Volume  Zero,  X  Protocol  Reference  Manual,  for 
a  detailed  discussion  of  the  X  protocol. 

resize  method 

The  resize  method  of  a  widget  is  called  when  the  widget's  parent  has  changed  its 
size.  This  method  is  part  of  the  Core  widget  class.  In  composite  widgets,  this 
method  calculates  a  new  layout  for  the  children.  In  simple  widgets,  this  method  re 
calculates  instance  variables  so  that  the  expose  method  can  redraw  the  widget 
properly. 

resource 

1)  A  widget  or  application  variable  whose  value  can  be  set  by  the  user  or  applica 
tion  programmer  via  the  Resource  Manager. 

2)  In  the  X  Protocol  and  server  documentation,  windows,  pixmaps,  cursors,  fonts, 
graphics  contexts,  and  colormaps  are  known  as  resources.  They  all  have  unique 
identifiers  (IDs)  associated  with  them  for  naming  purposes. 

resource  database 

The  resource  database  is  the  collection  of  possible  places  where  resource  specifi 
cations  can  be  made.  The  most  important  of  these  are  the  application-defaults  file, 
where  the  programmer  specifies  resource  defaults,  the  RESOURCE_MANAGER  server 
property,  which  the  user  can  set  with  xrdb,  and  the  Xdefaults  file  in  the  user's 
home  directory,  where  he  or  she  specifies  local  resource  preferences. 

Resource  Manager 

The  Resource  Manager  is  a  part  of  Xlib  that  merges  a  database  consisting  of  sever 
al  ASCII  files,  a  server  property,  and  values  hardcoded  by  the  application,  and  de 
termines  a  unique  value  for  each  resource  of  each  widget  It  resolves  conflicts  be 
tween  multiple  settings  for  the  same  resource  according  to  its  internal  precedence 
rules,  and  provides  the  widget  or  application  with  the  resulting  value. 

resource  setting 

A  resource  setting  is  the  actual  value  of  a  resource  variable. 
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resource  specification 

A  resource  specification  describes  a  "pathname"  to  a  widget  resource,  using  widg 
et  class  and/or  instance  names,  resource  class  or  instance  names,  and  optional  wild 
cards.  For  example,  the  resource  specification: 

xbox. box. quit .label:  Quit 

specifies  that  the  label  resource  of  the  quit  widget,  which  is  contained  in  the  box 
widget  in  the  xbox  application,  should  be  set  to  "Quit."  The  specification: 

* Command. background:  blue 

which  uses  wildcards  and  widget  classes,  specifies  that  the  background  (color)  re 
source  of  all  Command  widgets  in  any  application  should  be  set  to  "blue."  It  is  up 
to  the  Resource  Manager  to  resolve  differences  between  resource  specifications, 
which  may  have  varying  levels  of  specificity  in  the  various  locations  that  make  up 
the  resource  database. 

RGB  values 

See  color  cell. 

root 

The  root  of  a  window,  pixmap,  or  graphics  context  (GC)  is  the  same  as  the  root 
window  of  whatever  drawable  was  specified  in  the  call  to  create  the  window,  pix 
map,  or  GC.  These  resources  can  be  used  only  on  the  screen  indicated  by  this  win 
dow.  See  root  window. 

root  window 

Each  screen  has  a  root  window  covering  it  It  cannot  be  reconfigured  or  unmapped, 
but  otherwise  acts  as  a  full-fledged  window.  A  root  window  has  no  parent 

round-trip  request 

A  request  to  the  server  that  generates  a  reply  is  known  as  a  round-trip  request.  See 
reply. 

save-set 

The  save-set  of  a  client  is  a  list  of  other  clients'  windows  which,  if  they  are  infer 
iors  of  one  of  the  client's  windows  at  connection  close,  should  not  be  destroyed, 
and  which  should  be  reparented  and  remapped  if  the  client  is  unmapped.  Save-sets 
are  typically  used  by  window  managers  to  avoid  lost  windows  if  the  manager 
should  terminate  abnormally.  See  reparenting  for  more  background  information. 

scan  line 

A  scan  line  is  a  list  of  pixel  or  bit  values  viewed  as  a  horizontal  row  (all  values 
having  the  same  y  coordinate)  of  an  image,  with  the  values  ordered  by  increasing  x 
coordinate  values. 

scan  line  order 

An  image  represented  in  scan  line  order  contains  scan  lines  ordered  by  increasing  y 
coordinate  values. 
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screen 

A  server  may  provide  several  independent  screens,  which  may  or  may  not  have 
physically  independent  monitors.  For  instance,  it  is  possible  to  treat  a  color  moni 
tor  as  if  it  were  two  screens,  one  color  and  the  other  black  and  white  or  to  have  two 
separate  color  and  monochrome  screens  controlled  by  one  server.  There  is  only  a 
single  keyboard  and  pointer  shared  among  the  screens.  A  Screen  structure  con 
tains  the  information  about  each  screen  and  the  list  is  a  member  of  the  Display 
structure. 

scrollbar 

A  scrollbar  is  an  area  on  a  window  that  allows  a  user  to  view  different  portions  of  a 
window's  information  by  scrolling,  or  moving. 

selection 

Selections  are  a  means  of  communication  between  clients  using  properties  and 
events.  From  the  user's  perspective,  a  selection  is  an  item  of  data  which  can  be 
highlighted  in  one  instance  of  an  application  and  pasted  into  another  instance  of 
the  same  or  a  different  application.  The  client  that  highlights  the  data  is  the  owner, 
and  the  client  into  which  the  data  is  pasted  is  the  requestor.  Properties  are  used  to 
store  the  selection  data  and  the  type  of  the  data,  while  events  are  used  to  synchro 
nize  the  transaction  and  to  allow  the  requestor  to  indicate  the  type  it  prefers  for  the 
data  and  to  allow  the  owner  to  convert  the  data  to  the  indicated  type  if  possible. 

server 

The  server  provides  the  basic  windowing  mechanism.  It  handles  IPC  connections 
from  clients,  demultiplexes  graphics  requests  onto  the  screens,  and  multiplexes  in 
put  back  to  the  appropriate  clients.  It  controls  a  single  keyboard  and  pointer  and 
one  or  more  screens  that  make  up  a  single  display. 

server  grabbing 

The  server  can  be  grabbed  by  a  single  client  for  exclusive  use.  This  prevents  pro 
cessing  of  any  requests  from  other  client  connections  until  the  grab  is  complete. 
This  is  typically  a  transient  state  for  such  tasks  as  rubber-banding,  or  to  execute  re 
quests  indivisibly. 

set_values  method 

The  Intrinsics  invoke  a  widget's  set_values  method  when  one  of  the  widget's  re 
source  values  is  changed.  This  method  should  return  TRUE  or  FALSE  to  indicate 
whether  the  widget's  expose  method  should  be  invoked. 

set_values_almost  method 

The  set_values_almost  method  is  invoked  when  a  parent  rejects  a  widget's  geome 
try  request,  but  the  parent  sends  back  a  compromise.  This  method  is  part  of  the 
Core  widget  class. 

set_values_hook  method 

A  widget  can  provide  a  set_values_hook  method  to  allow  the  application  to  set  re 
sources  of  subparts. 
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sibling 

Children  of  the  same  parent  window  are  known  as  sibling  windows. 

spring-loaded  pop  up 

When  a  button  press  triggers  a  pop  up,  the  pop  up  is  called  a  spring-loaded  pop  up. 

stacking  order 

Sibling  windows  may  stack  on  top  of  each  other,  obscuring  lower  windows.  This  is 
similar  to  papers  on  a  desk.  The  relationship  between  sibling  windows  is  known  as 
the  stacking  order.  The  first  window  in  the  stacking  order  is  the  window  on  top. 

StaticColor 

The  StaticColor  visual  class  represents  a  multiplane  color  screen  with  a  predefined 
and  read-only  hardware  colormap.  It  can  be  viewed  as  a  degenerate  case  of 
Pseudocolor.  See PseudoColor. 

StaticGray 

The  StaticGray  visual  class  represents  a  multiplane  monochrome  screen  with  a 
predefined  and  read-only  hardware  colormap.  It  can  be  viewed  as  a  degenerate 
case  of  Grayscale,  in  which  the  gray  values  are  predefined  and  read-only.  Typi 
cally,  the  values  are  linearly  increasing  ramps.  See  Grayscale. 

stipple 

A  stipple  is  a  single  plane  pixmap  that  is  used  to  tile  a  region.  Bits  set  to  1  in  the 
stipple  are  drawn  with  a  foreground  pixel  value;  bits  set  to  0,  with  a  background 
pixel  value.  The  stipple  and  both  pixel  values  are  members  of  the  GC. 

status 

Many  Xlib  functions  return  a  status  of  TRUE  or  FALSE.  If  the  function  does  not 
succeed,  its  return  arguments  are  not  disturbed. 

subclass 

A  widget  subclass  has  its  own  features  plus  many  of  the  features  of  its  superclasses. 
For  example,  since  Composite  is  a  subclass  of  Core,  Composite  has  all  the  fields  in 
Core  plus  its  own  unique  fields.  A  subclass  can  inherit  or  replace  most  superclass 
features. 

superclass 

One  widget  is  a  superclass  of  a  second  widget  when  the  second  widget  includes  the 
first,  or  the  Core  widget  is  a  superclass  of  the  Composite  widget  because  the  Com 
posite  widget's  definition  depends  on,  or  includes,  the  Core  widget 

tight  binding 

A  tight  binding  refers  to  the  use  of  a  dot  (.)  in  a  resource  specification  to  indicate 
that  the  widget  class  or  instance  on  the  right  side  of  the  dot  is  a  child  of  the  widget 
whose  class  or  instance  name  is  on  the  left  side  of  it 

tile 

A  pixmap  can  be  replicated  in  two  dimensions  to  tile  a  region.  The  pixmap  itself  is 
also  known  as  a  tile. 
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time 

A  time  value  in  X  is  expressed  in  milliseconds,  typically  since  the  last  server  reset. 
Time  values  wrap  around  (after  about  49.7  days).  One  time  value,  represented  by 
the  constant  CurrentTime,  is  used  by  clients  to  represent  the  current  server 
time. 

top-level  window 

A  child  of  the  root  window  is  referred  to  as  a  top-level  window. 

translation 

A  translation  maps  an  event  or  event  sequence  into  an  action  name.  Once  a  trans 
lation  is  installed  in  a  widget,  the  named  action  function  will  be  invoked  when  the 
specified  event  seqeunce  occurs  in  the  widget  Translations  are  specified  as  ASCII 
strings. 

translation  table 

A  translation  table  lists  one  or  more  translations. 

TrueColor 

The  TrueColor  visual  class  represents  a  high-performance  multiplane  display  with 
predefined  and  read-only  RGB  values  in  its  hardware  colormap.  It  can  be  viewed 
as  a  degenerate  case  of  DirectColor,  in  which  the  subfields  in  the  pixel  value 
directly  encode  the  corresponding  RGB  values.  Typically,  the  values  are  linearly 
increasing  ramps.  See  DirectColor. 

type  property 

A  type  property  is  used  to  identify  the  interpretation  of  property  data.  Types  are 
completely  uninterpreted  by  the  server;  they  are  solely  for  the  benefit  of  clients. 

viewable 

A  window  is  viewable  if  it  and  all  of  its  ancestors  are  mapped.  This  does  not  imply 
that  any  portion  of  the  window  is  actually  visible,  since  it  may  be  obscured  by  oth 
er  windows. 

visible 

A  region  of  a  window  is  visible  if  someone  looking  at  the  screen  can  actually  see  it; 
that  is,  the  window  is  viewable  and  the  region  is  not  obscured  by  any  other  win 
dow. 

visual 

The  specifications  for  color  handling  for  a  window,  including  visual  class,  depth, 
RGB/pixel,  etc.,  are  collectively  referred  to  as  a  visual,  and  are  stored  in  a  structure 
of  type  visual. 

visual  class 

Visual  class  refers  to  DirectColor,  Grayscale,  Pseudocolor, 
StaticColor,  StaticGray,  or  TrueColor.  It  is  a  definition  of  the  color- 
map  type  but  not  its  depth. 
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widget 

The  basic  object  in  a  toolkit,  a  widget  includes  both  code  and  data,  and  can  there 
fore  serve  as  an  input  or  output  object. 

window  gravity 

When  windows  are  resized,  subwindows  may  be  repositioned  automatically  by  the 
server,  relative  to  an  edge,  corner,  or  center  of  the  window.  This  attraction  of  a 
subwindow  to  some  part  of  its  parent  is  known  as  window  gravity.  Window  gravity 
is  a  window  attribute.  See  also  bit  gravity. 

window  manager 

The  user  manipulates  windows  on  the  screen  using  a  window  manager  client.  The 
window  manager  has  authority  over  the  arrangement  of  windows  on  the  screen,  and 
the  user  interface  for  selecting  which  window  receives  input.  See  also  redirect. 

XYPixmap 

The  data  for  an  image  is  said  to  be  in  XYPixmap  format  if  it  is  organized  as  a  set  of 
bitmaps  representing  individual  bit  planes.  This  applies  only  to  the  server's  inter 
nal  data  format  for  images.  It  does  not  affect  normal  programming  with  pixmaps. 

ZPixmap 

The  data  for  an  image  is  said  to  be  in  ZPixmap  format  if  it  is  organized  as  a  set  of 
pixel  values  in  scan  line  order.  This  applies  only  to  the  server's  internal  data  for 
mat  for  images.  It  does  not  affect  normal  programming  with  pixmaps. 

zoomed  window 

Some  applications  have  not  only  a  normal  size  for  their  top-level  window  and  an 
icon,  but  also  a  zoomed  window  size.  This  could  be  used  in  a  painting  program 
(similar  to  the  MacPaint™  fat  bits).  The  zoomed  window  size  preferences  can  be 
specified  in  the  window  manager  hints. 
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Master  Index 


77?e  Master  Index  combines  Volumes  Four  and  Five  index  entries,  making  it 
easy  to  look  up  the  appropriate  references  to  a  topic  in  either  volume.  PM 
refers  to  the  X  Toolkit  Intrinsics  Programming  Manual.  RM  refers  to  the  X 
Toolkit  Intrinsics  Reference  Manual. 


Index 


The  Master  Index  combines  Volumes  Four  and  Five  index  entries,  making  it  easy  to  look  up 
the  appropriate  references  to  a  topic  in  either  volume.  PM  refers  to  the  X  Toolkit  Intrinsics 
Programming  Manual.  RM  refers  to  the  X  Toolkit  Intrinsics  Reference  Manual. 

The  alphabetical  sequence  of  the  index  is  highlighted  by  the  bolding  of  primary  entries. 


#  directive  (see  translations) 
!  (see  modifiers) 

-  options  (see  options) 


accelerators,  about  PM:53, 150, 189, 205-211, 
253, 495 

(see  also  display _accelerator) 

(see  also  XtlnstallAccelerators) 

(see  also  XtlnstallAllAccelerators) 

compiling  accelerator  table  PM:210;  RM:201 

defining  default  table  in  code  PM:210 

display_accelerator  method  PM:21 1 ;  RM:320 

event  propagation  PM:207 

for  gadgets  PM:371 

for  menus  PM:367,371 

installing  PM:205;  RM:166-168;  in  multiple 
widgets  PM:209 

not  usable  in  gadgets  PM:373 

parsing  (see  compiling) 

translations;  conflicts  with  PM:209;  transla 
tion  table  limitations  PM:206 
accept_focus  method,  about  PM:154, 389, 391, 

495 

AcceptFocusProc  RM:328 
access  control  list  PM:495 
actions  PM:30, 495 

(see  also  XtAddActions,  XtAppAddActions) 


actions,  about  PM:27, 39;  RM:7, 428 
action  proc;  format  PM:46 
actions  table,  PM:495;  adding  PM:43-45; 
RM:42 -43,  60-61;  declaring/registering 
with  Resource  Manager  RM:60-61; 
example  PM:45;  format  PM:45;  XtAc- 
tionProc  RM:270-272 
adding;  from  application  PM:43;  in  widget 

itself  PM:  184-1 86 
arguments  to  PM:113 
contrasted  with  callbacks  PM:46, 1 12 
defined  in  widget  implementation  file 

PM:  145-147 

gadget  parent;  example  PM:380-381 
in  gadgets  PM:373 
naming  conventions  PM:42 
passing  arguments  to  PM:113 
registering  (see  adding) 
using  event  data  PM:222;  example 

RM:27 1-272 

widget  instance  pointer  PM:185 
widget/application  conflicts  PM:146 
(see  also  XtAddActions,  XtAppAddActions) 
aliasing  font  names  PM:443 
AlmostProc  RM:328 
Alt  key  (see  modifiers) 
ancestor  PM:496 
anonymous  ftp  PM:34 
application  contexts,  about  PM:97-99, 
393-396, 496 
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adding  display  RM:135-136;  XtOpenDisplay 

PM:98,396;RM:195-196 
creating  RM:115-116 
destroying  and  closing  displays  RM:127 
explicit  PM:98 

main  loop  for  multiple  PM:394 
multiple  PM:394 

(see  also  XtCreateApplicationContext) 
(see  also  XtDestroyApplicationContext) 
(see  also  XtWidgetToApplicationContext) 
application,  application  resources  PM:80;  data 
structure  PM:81;  retrieving  values  PM:85 
application-defaults  file,  about  PM:32,  36, 
245;  directory  PM:36;  naming  conven 
tions  PM:32,  36 
applicationShellWidgetClass  PM:270; 

RM:346-353 
Arg  structure  PM:92 
argc  PM:33,91,272 
ArgList  (see  argument  lists) 
ArgsProc  RM:327 
ARGSUSED  PM:42 

arguments,  argument  lists;  about  PM:92,  496; 
constructing/modifying  dynamically 
RM:232-233;  creating  PM:92;  creating 
dynamically  PM:93;  creating  with 
XtSetArg  PM:93-94;  example  PM:92-93; 
merging  ArgList  RM:186;  XtMergeAr- 
gLists  RM:186 
argument  styles  PM:90 
command  line  RM:13 
to  actions  PM:113,  124 
to  type  converters  PM:259-260 
argv  PM:33,91,272 
array  (see  also  XtNumber) 
allocating  RM:105 

elements,  determining  number  RM:192 
(see  also  XtCalloc) 
aspect  ratio  PM:274 
Athena  widgets,  about  PM:17,  496 
Box  PM:66;  RM:357-358 
Command  PM:19, 40-43, 47,  65;  RM:359-362 
Dialog  PM:71, 75, 340-341;  RM:363-364 
Form  PM:68-69, 325-340;  RM:365-367 
Grip  PM:66;  RM:368-369 
inheritance  among  PM:18 
Label  PM:  19, 36, 240;  RM:370-372 
List  RM:373-377 
MenuButton  PM:367 

Scroll  PM:15, 39,  42,  66,  109;  RM:378-382 
Simple  PM:19 

SimpleMenu  PM:349,  367-371, 378-381 
Template  RM:383-390 


Text  PM:75,  150.  264,  280;  RM:391-402 

Viewport  PM:107,  310,  314;  RM:403-404 

Vpaned  PM:66 

VPaned  PM:310 

Vpaned  RM:405-408 
atoms,  about  PM:288, 496 

obtaining;  example  PM:29 1,292 

predefined  PM:291 

standard  PM:299 
augmenting  translations  PM:48 
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background  PM:53,  496 

background  processing  PM:23 1 ;  RM:323-324 

pixmap  PM:53 

window  attribute  PM:156 
backing  store  PM:257, 496 

window  attribute  PM:156 
binding,  tight  vs.  loose  (resources)  PM:244 
bit  gravity  PM:496 
bit  plane  PM:497 

bit_gravity  window  attribute  PM:156 
bitmap  PM:279,497 

bitmap  files  PM:104 

BitmapEdit  widget,  about  PM:66,  104,  177, 
314,461 

BitmapEditClassRec,  example  PM:138-139 

BitmapEditRec,  example  PM:139 
bitwise  RM:50,95 
Boolean  values  PM:253 
border  PM:497 

border  crossing  events  RM:454-459 

border  width  PM:306 

border  window  attribute  PM:156 
bounding  box  PM:171;RM:295 
Box  widget  PM:21,  61-71,206-211,351-358 

examples  PM:61-66 

geometry  management  RM:357-358 

resources  RM:357-358 
BulletinBoard  widget  PM:409 
ButtonPress  events  PM:196, 353;  RM:439-441 
UuttonRelea.se  events  PM:196,  353; 

RM:439-441 
buttons  (see  also  command  buttons) 

grabbing  PM:497 

mapping  RM:477 
byte  order  PM:497 
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caching,  old  size  PM:179 

standard  atoms  PM:299 

type  conversions  PM:260 

Xmu;  initializing  PM:300 
callbacks,  about  PM:26,  30,  39,  497;  RM:6, 
330, 429 

adding  PM:40,  42;  more  than  one  at  a  time 
PM:80;  to  callback  list  RM:46-47;  to  call 
back  resource  RM:44-45 

arguments  to  PM:42 

callback  list,  about  PM:79,  RM:6;  deleting 
method  RM:219;  deleting  method  list 
RM:220;  determining  status  RM:160; 
executive  methods  RM:104;  popping 
down  widget  RM:102-103;  popping  up 
widget  RM:98-101;  XtCaUbackExclusive 
RM:98-99;  XtCaUbackNone  RM:100; 
XtCallbackNonexclusive  RM:101; 
XtCallbackPopdown  RM:  102-103;  XtCall- 
Callbacks  RM:104;  XtHasCallbacks 
RM:160;  XtRemoveCallback  RM:219; 
XtRemoveCallbacks  RM:220 

contrasted  with  actions  PM:46 

format  PM:42 

naming  conventions  PM:42 

passing  data  PM:77-79 

pop-up  functions  PM:79 

procedure  RM279-280 

(see  also  XtAddCallback,  XtCallbackProc) 

(see  also  XtTimerCallbackProc) 
Caption  widget,  about  PM:409 
cascading  pop  ups,  about  PM:345-347, 
362-367 

example  PM:363-365 
case  converter  PM:200 

registering  RM:216 

(see  also  XtRegisterCaseConverter) 
chained  methods  (see  inheritance) 
change_managed  method  PM:306-308, 319, 
497;  RM:340 

in  constraint  widgets  PM:338-339 
CirculateNotify  events  RM:442 
CirculateRcqucst  events  RM:443 
class,  about  PM:18,498 

class  name;  defined  in  Core  class  part  PM:150 

class  part  PM:137;  combining  into  class 
record  PM:138;  lack  of  new  fields 
PM:138 

class  record  PM:136;  allocating  storage 
PM:140;  BitmapEdit  widget  PM:138-139; 
contents  PM:136 


class_initialize  method  PM:153,  258, 381, 
498;RM:331 

class jpart_init  method  PM:153,  331;  RM:331 

hierarchy  (see  widget  classes);  Athena  widgets 
PM:153;  gadgets  PM:375 

structures  PM:136-162 

subclass;  about  RM:14 
client,  about  PM:6, 498 

ClientMessage  events  RM:444-445 

client-server  model  PM:6 
clipping  region  PM:498 
color  PM:53, 56, 120, 156-158, 253-254, 276 

co lor  names  PM:433 

colorcell,  about  PM:436,  498;  read-only 
PM:438;  read/write  PM:438;  shared 
PM:437 

colormap,  about  PM:53,  436,  498;  installing 
PM:276;  window  attribute  PM:156 

ColormapNotify  events  RM:446 

determining  available  PM:436 

displaying  PM:436 

false  PM:277 

hexadecimal  specification  PM:434 

RGB  model  PM:435 

specifying  PM:433 
command  buttons  PM:404, 406, 417; 

RM:359-362 
command  line  options  (see  options) 

compiling  PM:34 

Command  widget  PM:206-210, 353-359, 362, 
366, 404-406, 417;  RM:359-362 

creating  RM:362 

destroying  RM:362 

resources  RM:359-361 
compiling  Xt  PM:34 
composite  widgets, 

as  parent  and  child  PM:320 

change_managed  method  RM:340 

class,  about  PM:16, 21, 137;  XtNinsertPosi- 
tion  resource  PM:324 

composite  widget  class;  about  PM:61 

delete_child  method  RM:340 

general  purpose  PM:409,  421 

geometry_manager  method  RM:340-341 

insert_child  method  RM:339-340 

insert_position  method  RM:342 

importance  PM:408 

initial  size  PM:309 

inserting  children  PM:323 

menus  and  control  areas  PM:418 

ordering  method;  XtOrderProc  RM:310 

reasons  for  writing  PM:305 

resources  (see  resources) 
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subclass;  XtlsComposite  RM:169 

using  within  other  widgets  PM:306 
compound  widgets  PM:340,  341 
com prcss_exposu res  event  filter  PM:172 
compression  filters  (see  event  filters) 
conditional  compilation  PM:36 
ConfigureNotify  events  RM:447-448 
ConfigureRequest  events  RM:449-450 
connection  PM:499 

constraint  widgets,  about  PM:  67, 305, 499; 
RM:  16, 343-345 

class,  about  PM:22, 137;  refiguring  child 
locations  PM:333-335 

constraint  class  part  PM:329 

constraint  management  PM:325-340 

constraint  methods;  change_managed 
PM:338;  set.values  PM:338 

constraint_destroy  method  RM:345 

constraint_initialize  method  RM:345 

destroy  method  PM:329 

geometry _manager  method  PM:332 

initialize  method  PM:329 

part  structure  PM:327 

resize  method  PM:336 

resources  PM:327,  RM:343-345;  example 
PM:68,  69 

set_values  method  RM:343 

(see  also  XtlsConstraint) 
containment  PM:499 
conventions,  action  function  names  PM:42 

application-defaults  file  PM:32,  36 

callback  function  names  PM:42 

font  naming  PM:439 

Xtlnherit  constants  PM:156 

function  typedef  naming  PM:148 

gadget  internals  PM:375 

instance  variables  order  PM:140 

keysym  naming  PM:195 

public  function  names  PM:1 14,  449 

resource;  class  PM:144;  names  PM:144; 
representation  types  PM:144;  resource 
names  PM:240 

widget  PM:  449-450;  internals  PM:136; 

source  file  names  PM:136;  structure  decla 
rations  PM:140, 162 
converters  PM:25 1-264 

color  name  to  pixel  value  PM:120,  253,  276 

Convert.h  PM:260 

filename  to  pixmap  PM:257 

fontname  to  font  PM:253 

fontname  to  font  struct  PM:253 

function  pointer  to  callback  list  PM:258 

int  to  Boolean  PM:254 


int  to  Dimension  PM:254 

int  to  float  PM:254 

int  to  font  PM:254 

int  to  pixel  PM:254 

int  to  pixmap  PM:254 

int  to  Position  PM:254 

int  to  short  PM:254 

int  to  unsigned  char  PM:254 

inttoXColor  PM:254 

invoking  directiy  PM:261 

Pixel  to  XColor  PM:254 

registering  RM:48,  62-64;  case  converter 
RM:216 

string  to  accelerator  table  PM:253 

string  to  boolean  PM:253 

string  to  cursor  PM:253,  257 

string  to  Dimension  PM:253 

string  to  Display  PM:253 

string  to  file  descriptor  PM:253 

string  to  float  PM:253 

string  to  int  PM:253 

string  to  orientation  mode  PM:257 

string  to  Position  PM:253 

string  to  short  PM:253 

string  to  translation  table  PM:253 

string -to -justify  mode  PM:257 

widget  name  to  widget  ID  PM:257 

widgets  (R2  to  3)  PM:453 

writing  a  converter  PM:262-264 

XColor  to  Pixel  PM:254 

(see  also  XtConvert,  XtDirectConvert) 
coordinate  system  PM:3, 499 
Core 

Core  class  part  fields 

accept_focus  method,  PM:154,  389,  391,  495; 
callback_private  PM:151;  class_initialize 
method  PM:153, 258, 381, 498;  RM:331; 
class_inited  PM:150;  class_part_init 
method  PM:153,331;RM:331; 
class_name  PM:150;  compress_enterleave 
PM:150;  compress_exposure  PM:150; 
compress_motion  PM:150;  destroy  method 
PM:154, 165, 183, 500;  RM:332;  dis- 
play_accelerator  field  PM:150;  extension 
PM:151;  get_values_hook  PM:150;  ini- 
tiaUze_hook  PM:  150;  initialize  method 
RM:328-329,  330-331;  query_geometry 
methodPM:154, 165, 180-182,306,321, 
508;  RM:336-337;  reaUze  method  realize 
method  PM:153,  274, 310, 315, 509; 
RM:331-332;set_values_hook  PM:150; 
superclass  PM:149;  tm_table  PM:150; 
version  PM:151;  visible_interest  PM:150; 
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widget_size  PM:150;  xnn_clas  PM:150; 
resize  method  PM:154,  165, 177-180,306, 
309, 316, 336-337, 380, 510;  RM:333; 
set_values  method  PM:154, 165-166, 
174-176, 311-312, 315, 512;  RM:319, 
334-335, 343 
Core  class  part  initializing;  example 

PM:  148-149 
Core  class  structure;  compress_exposures  field 

PM:172,RM:297;  in  gadgets  PM:375 
Core  widget  class  (see  also  XtExposeProc); 

XtN  (see  resources) 

Core  widget  class  PM:17, 19, 52, 137, 499; 
RM:327-337;  class  pointer  PM:119; 
class_initialize  method  RM:331; 
class_part_initialize  method  RM:331; 
compress_enterleave  field  PM:234;  com- 
press_exposure  field  PM:234;  com- 
press_motion  field  PM:234;  destroy 
method  RM:332;  display _accelerator 
method  RM:336;  drawing  into  from  appli 
cation  PM:117, 118,  119;  expose  method 
PM:171-172;  RM:296, 332-333;  get_val- 
ues_hood  method  RM:335;  hidden  superc 
lasses  PM:155;  initialize  method 
RM:328-329,  330-331;  initialize_hook 
method  RM:336;  instance  default  size 
PM:119;  methods  RM:330;  query  _geome- 
try  method  RM:336-337;  reaUze  method 
RM:331-332;  resize  method  RM:333; 
resources  PM:52;  set_values  method 
RM:334-335;  set_values_almost  method 
RM:335;  set_values_hood  method 
RM:335;  superclasses  PM:374;  visi- 
ble_interest  field  PM:230;  widgetClass 
class  pointer  PM:119 
CoreClassPart  structure  PM:139 
CorePart  structure  PM:139 
instance  record;  height  field  PM:308;  width 

field  PM:308 
instance;  setting  size  PM:119 

counter  incrementing  inside  XtSetArg  PM:51 

CreateNotify  events  RM:45 1-452 

Ctrl  key  (see  modifiers) 

cursor  PM:  157,  253,499 
cursor  window  attribute  PM:157 

cut  and  paste  (see  selections) 


D 


data  types  RM:423 

database  (see  also  XtDatabase);  obtaining  for 

display  RM:126 
DECNet  PM:280 
decoration  PM:3 1,279 
default  size  PM:180 
delete_child  method  PM:306, 323-324,  500; 

RM:340 

depth  PM:53, 169,  500 
dereference  PM:500 
descendants  PM:500 
destroy  method  PM:154, 165, 183, 500; 

RM:332 

DestroyNotify  events  RM:453 
details  in  translations  (see  translations) 
device  PM:500 
dialog  boxes  PM:371 

cascading  PM:371 

grabs  in  PM:371 

without  grabs  PM:371 
Dialog  widget  RM:363-364 

adding  children  RM:364 

creating  RM:364 

destroying  RM:364 

removing  children  RM:364 

resources  RM:363-364 
DirectColor  PM:500 
directories,  font  PM:438 
display  (see  also  XtDisplaylnitialize) 

about  PM:6, 500 

adding;  XtOpenDisplay  RM:195-196 

closing  RM:108 

connecting  to  multiple  PM:396 

depth  PM:436 

DISPLAY  environment  variable  PM:53 

lists  PM:171;RM:295 

pointer,  returning  for  widget  RM:134 

display_accelerator  method,  (see  also 
XtStringProc);  PM:211;  RM:320, 336 

initializing  RM:  135-136 

(see  also  XtCloseDisplay) 
distributed  processing,  about  PM:7 
DoesBackingStore  Xlib  macro  PM:156 
DoesSaveUnders  Xlib  macro  PM:156 
double-clicks  PM:43,201 
downward  chaining  PM:152 
drawing,  about  PM:  119-120, 140,  150-152, 
165, 170-174 

after  Expose  event  PM:153 

bitmap  cells  PM:161 

coordinate  system  PM:3 
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due  to  set_values  method  changes  PM:175 
in  expose  method  PM:166 
into  Core  widget  PM:117-119 
window  attributes  PM:156-157 
drop-down  menu  (see  menus) 


elements  (see  array) 
encapsulation  PM:29,  500 
enter/leave  compression  PM:234 
EnterNotify  events  PM:  195-196, 234, 353; 

RM:454-459 

EnterWlndow  events  PM:216 
environment  variables,  DISPLAY  PM:53 

XAPPLRESDIR  PM:245 

XENVIRONMENT  PM:245 
errors,  error  database;  obtaining  RM:74, 75-77, 
144;  XtAppGetErrorDatabase  RM:74, 
145;  XtAppGetErrorDatabaseText 
RM:75-77, 144 

error  handling  PM:91,93;  and  application 
contexts  PM:387;  calling  error  resource 
database  PM:386;  caUing  fatal  error  han 
dler  RM:71-73,  85-86, 137-139, 234;  .XF2 

listing  RM:491 

string  conversion  error  message  RM:248 
events,  event  loop  (see  main  loop) 
events  (see  also  exposure) 

(see  also  XtDispatchEvent) 

(see  also  XtMainLoop,  XtNextEvent) 

about  PM:10, 191,501;RM:7 

accessing  specific  data  RM:437 

as  argument  of  action  PM:46 

border  crossing  RM:454-459 

ButtonPress  RM:439-441 

ButtonRelease  RM:439-441 

cancelling  source  RM:224 

CirculateNotify  RM:442 

CirculateRequest   RM:443 

CUentMessage  RM:444-445 

ColormapNotify  RM:446 

ConfigureNotify  RM:447-448 

ConfigureRequest  RM:449-450 

CreateNotify  RM:45 1-452 

DestroyNotify    RM:453 

dispatching  handlers  RM:133 

EnterNotify  PM:234;  RM:454-459 

EnterWindow  PM:216 

event  compression  PM:501 

event  data;  using  in  an  action  PM:222 

event  filters  PM:  150,  234 


event  handlers,  about  PM:28,  30,  215-220, 
501;RM:7;  adding  PM:216;  dispatching 
RM:133;  for  nonmaskable  events 
PM:219-220;  procedure  RM:293-294, 
304-305;  raw  PM:220;  reasons  to  use 
PM:216;  registering  RM:49-50;  register 
ing  raw  RM:56-57;  removing 
RM:221-222;  removing  raw  RM:225-226; 
XtAddEventHandler  RM:49-50;  XtAdd- 
RawEventHandler  RM:56-57; 
XtEventHandler  RM:293-294;  Xdn- 
putCallbackProc  RM:304-305;  XtRemove- 
EventHandler  RM:221-222;  XtRemove- 
RawEventHandler  RM:225-226 

event  masks,  about  PM:216,  501;  RM:424; 
retrieving  RM:95-96;  table  PM:216; 
XtBuildEventMask  RM:95-96 

event  members;  common  RM:438 

event  processing  RM:84;  XtAppProcessEvent 
RM:84 

event  propagation  PM:501 

event  queue  PM:234;  peeking  PM:234 

event  sequences;  sharing  initial  events 

PM:204;  sharing  noninitial  events  PM:204 

event  source  PM:501 

event  structure  PM:221 

event-driven  programming,  about  PM:10-11 

event_mask  window  attribute  PM:157 

expose  PM:10 

Expose  PM:23, 153, 235;  RM:460-461 

Focusln  PM:216;  RM:462-467 

FocusOut  PM:216;RM:462-467 

frozen  event  PM:502 

GraphicsExpose  PM:193, 220;  RM:468-469 

GravityNotify  RM:470 

in  action  routines  PM:124 

in  gadgets  PM:373 

input  events;  XtRemovelnput  RM:224 

KeymapNotify  RM:471 

KeyPress  RM:472-474 

KeyRelease  RM:472-474 

LeaveNotify  PM:234;  RM:454-459 

LeaveWindow  PM:216 

list  of  types  and  structure  names  PM:223 

MapNotify  RM:475-476 

MappingNotify  RM:477-478 

MapRequest  RM:479 

mocking  up  from  action  PM:171;RM:295 

MotionNotify  PM:216,  234;  RM:480-482 

next  event;  returning  RM:191 

NoExpose  PM:193;RM:468-469 

nonmaskable  PM:  1 9 1 , 207, 2 1 8 

processing  RM:176 
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processing  one  event;  XtProcessEvent 
RM:209 

propagation  PM:207 

PropertyNotify  RM:483 

ReparentNotify   RM:484 

ResizeRequest  RM:485 

returning  next  event  RM:80 

selecting  PM:207 

SelectionClear  PM:280,  289;  RM:486 

SelectionNotify  PM:280,  290,  295;  RM:487 

SelectionRequest  PM:280, 282,  290-291; 
RM:488 

structures  RM:438 

translation  table  abbreviations  PM:  192- 193 

UnmapNotify  RM:475-476 

using  inside  actions  or  event  handlers  PM:221; 
RM:271 

VisibiUtyNotify  RM:489-490 

XEvent;  example  PM:221;  RM:271 

(see  also  XtAppNextEvent,  XtAppPending) 
examples,  actions;  actions  table  PM:45;  adding 
actions  PM:43-45;  in  gadget  parent 
PM:380-381;  using  event  data  in  PM:222; 
widget  actions  PM:  184- 185 

adding;  accelerators  PM:206;  event  handler 
PM:218-219;  RM:294;  resource  list  to  class 
structure  PM:145;  scrollbars  to  appUcation 
PM:  109,  111;  work  procedure 
PM:23 1-232 

appUcation  resource  data  structure  PM:81 

BitmapEditClassRec  PM:  138-139, 138 

BitmapEditRec  PM:139 

calculating  scrollbar  thumb  size  PM:  1 13-1 16 

cascading  pop-up  menu  PM:363, 365 

constraint  resources  PM:68-69 

constraint  widget  change_managed  method 
PM:338-339 

constraint  widget;  refiguring  child  locations 
PM:333-335 

converting;  default  value  of  resource 

PM:254-255;  selection  PM:293-294;  stan 
dard  selections  PM:300-301;  RM:284-285 

creating;  argument  Ust  PM:92;  argument  lists 
withXtSetArg  PM:93,  94;  GCs  from  ini 
tialize  method  PM:169-170;  iconpixmap 
PM:278-279 

creating  pop  up;  work  procedure  RM:323 

creating;  widget  hierarchy  PM:61-63 

declaring;  resource  Ust  PM:240;  widget  class 
record  pointer  PM:155 

destroy  method  PM:183 

drawing  into  Core  widget  PM:1 18-1 19 

explicitly  invoking  converter  PM:261 


expose  method  PM:171-172;  RM:296;  in  gad 
get  parent  PM:378-379 

gadget  class  structure  PM:376 

gadget  instance  structure  PM:377 

geometry_manager  method  in  constraint 
widget  PM:332-333 

get_values_hook  method  PM:265;  RM:277 

hardcoding  resources  PM:92 

highUghting  selection  PM:284-288 

initialize  method  PM:166-168;  in  constraint 
widget  PM:330 

initiaUzing;  Core  class  part  PM:  148-149; 
Xmu  atom  caching  PM:300 

installing  accelerators  in  multiple  widgets 
PM:209 

interactions  between  resources  PM:55 

laying  out  child  widgets  PM:3 17-3 19 

main  loop  (custom)  PM:233 

menu  using  SimpleMenu  widget  PM:368-370 

nonmaskable  event  handlers  PM:219-220 

obtaining;  atom  PM:29 1-292;  source  code 
availabiUty  PM:34 

options  table  PM:88-89 

passing  arguments  to  converter  PM:259 

passing  data  PM:77-79 

pasting  selection  PM:295-296 

placing;  drop-down  menu  PM:360, 361; 
pop-up  menu  PM:354,  357 

pop  ups;  work  procedure  to  create  PM:232 

pop-up  menu  (spring-loaded);  using  Box 
widget  PM:354-358 

pubUc  function  to  get  widget  data  PM:  105 

query_geometry  method  PM:182;  in  compos 
ite  widget  PM:316-317;  in  constraint 
widget  PM:339 

reading;  from  file  PM:224-226;  from  pipe 
PM:226-227 

registering  resource  converter  PM:258 

removing  timeouts  PM:229-230 

resize  method  PM:177, 179;  in  composite 
widget  PM:316;  in  constraint  widget 
PM:336-337;  in  gadget  parent  PM:380 

resource  definition  in  widget  PM:  143 -145 

resource  list  PM:82-83 

resource  value;  getting  PM:51 

retrieving;  appUcation  resources  PM:85-86; 
resource  default  at  run-time  PM:256 

setting;  resources  for  widget  hierarchy  PM:64; 
resources  with  XtSetValues  PM:50;  win 
dow  attributes  in  realize  method  PM:157; 
XtNinput  PM:276 

set_values  method  PM:  174-175;  in  composite 
widget  PM:316 
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timeouts  PM:228-229 

translation  table  PM:47 

using;  argument  lists  PM:92-93;  event  data  in 
an  action  PM:222;  RM:27 1-272;  popups 
PM:71-74;  timeouts  PM:229 

writing  type  converter  PM:262-263 

xbitmapl  PM:104-107 

xbitmap2  PM:  107-1 16 

xbitmapS  PM:1 16-122 

xbitmap4  PM:  123-132 

XEvent  RM:271 

XEvent  casting  PM:221 

xfarewell.c  PM:43-45 

xgoodbye.c  PM:40 

xheUo.c  PM:31-32 

XrmOptionDescRec  PM:88-89 

(see  also  XtResourceDefaultProc) 
expo.lcs.mit.edu  PM:34 
Expose  events  PM:10,  23, 114, 122, 124, 150, 
153, 165, 172, 230, 235,  353;  RM:51, 297, 
460-461 

expose  method  PM:29, 153, 165-166, 170-174, 
220, 501;  RM:296-297, 332-333 

in  gadget  parent  PM:378-379 

in  gadgets  PM:373,  378 

(see  also  XtExposeProc) 
exposure  PM:501 

(see  also  Expose  events) 

(see  also  XtAddExposureToRegion) 

compression  PM:172,  235;  RM:297 
exposure  (see  Expose  events) 
extensions,  about  PM:12,  502 


fatal  error  handling  (see  errors) 
fatal  error  (see  errors) 
file  input,  registering  file  RM:65-66 
files,  file  events  (see  event  handlers) 
file  input  PM:224-226;  registering  file 

RM:54-55;  source  masks  PM:224;  XtAd- 

dlnput  RM:54-55;  XtAppAddlnput 

RM:65-66 

filenames;  character  limit  PM:136 
using  names  in  resources  PM:253 
floating  point  numbers  PM:253 
Focusln  events  PM:195-196,216,390; 

RM:462-467 
FocusOut  events  PM:195-196,216,390; 

RM:462-467 
font  conventions  (in  this  book),  bolding 

PM:xxviii;  RM:viii 


italics  PM:xxviii;  RM:viii 

typewriter  font  PM:xxviii;  RM:viii 
fonts  PM:502 

aliasing  PM:442 

creating  databases  (mkfontdir)  PM:444 

directories  PM:438 

display  (xfd)  PM:438 

families  PM:438,441 

fonts.dir  files  PM:444 

naming  convention  PM:439 

printer  PM:438 

screen  PM:438 

specifying  PM:433;  as  resources  PM:253 

using  file  name  as  alias  PM:443 

wildcarding  PM:441 
foreground  PM:502 

Form  widget,  about  PM:20,  67-70, 325-340, 
409,421;RM:365-367 

adding  children  RM:367 

child  resources  RM:366 

creating  RM:367 

deleting  children  RM:367 

destroying  RM:367 

example  PM:421 

layout  method  PM:329 

resources  RM:365-366  (see  also  resources) 
freeing  storage  block  (see  storage  block) 
ftp  PM:34 
function  typedefs,  overlapping  use  PM:148 


G 


gadgets,  about  PM:155,  345 
accelerators  PM:371;  not  usable  PM:373 
actions  in  PM:373 
class  hierarchy  PM:374-375 
class  structure  PM:376 
composite  parent  PM:373,  378-381 
Core  class  structure  PM:375 
drawbacks  PM:373 
event  handling  in  PM:373 
expose  method  PM:378 
implementation  file  PM:377 
instance  structure  PM:377 
internals  PM:375-378 
private  header  file  PM:376-377 
public  header  file  PM:378 
query_geometry  method  PM:378 
reason  for  PM:372 
set_values_almost  method  PM:378 
Sme  PM:367-378 
SmeBSB  PM:367-378 
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SmeLine  PM:367-378 
superclass  PM:377 
unused  Core  fields  in  PM:377-378 
games  PM:227 
GC  (see  graphics  contexts) 
geometry  management,  about  PM:33,  65-66, 

177, 180-182, 273, 305-341, 502;  RM:14, 

338-342,431 

(see  also  XtDestroyWidget) 
(see  also  XtGeometry Almost) 
(see  also  XtGeometry  Done  return  value) 
(see  also  XtGeometryNo  return  value) 
(see  also  XtGeometryResult  enum) 
(see  also  XtGeometry  Yes  return  value) 
(see  also  XtlnheritDeleteChild  constant) 
(see  also  XtlnheritGeometryManager  constant) 
(see  also  XtlnheritlnsertChild  constant) 
(see  also  XtlnheritSetValuesAlmost  constant) 
(see  also  XtMakeGeometryRequest) 
(see  also  XtMakeResizeRequest) 
(see  also  XtMapWidget,  XtMoveWidget) 
(see  also  XtNinsertPosition  composite 

resource) 
(see  also  XtNmappedWhenManaged  Core 

resource) 

(see  also  XtQueryGeometry) 
(see  also  XtResize Widget) 
(see  also  XtUnmanageChild,  XtUn- 

manageChildren) 
(see  also  XtUnmap Widget) 
(see  also  XtWidgetGeometry  structure) 
almost  right  PM:323 
border  width  PM:306 
Box  widget  RM:357-358 
change_managed  method  PM:306,  308,  319 
changes  PM:456;  RM:  177-179 
changing;  XtMakeGeometryRequest 

RM:177-179 

compound  widgets  PM:340-341 
constraint  class  part  PM:329 
constraint  management  PM:325 
constraints  on  children  RM:365-367 
delaying  recalculation  PM:340 
delete_child  method  PM:306,  323-324 
geometry  handler;  procedure  RM:299-301 
geometry  manager  RM:341 
geometry_manager  method  PM:306,  311, 

320-322;  RM:340-341;  in  constraint  widget 

PM:332-336 
height  PM:308 

initial  geometry  negotiation  PM:308, 310 
initial  size  PM:308 
initialize  method  PM:315 


inserting  children  PM:323;  insert_child 

method  PM:306, 323-324 
minimal  useful  size  PM:317 
querying  RM:210-212;  preferred  geometry 

PM-.320;  query_geometry  method  PM:306, 

321;  XtQueryGeometry  RM:210-212; 

XtQueryOnly  constant  PM:322 
realize  method  PM:310,315 
resizing  PM:305, 311;  by  application 

PM:312;  by  user  PM:311;  by  widget 

request  PM:311-312;  resize  method 

PM:306, 309 
scope  PM:306 

scroUable  widget  RM:403-404 
set_values  method  PM:3 1 1  -3 12,  3 15 
set_values_almost  method  PM:312,  322,  323 
size  preferences  PM:320 
stacking  order  PM:306, 341 
trickle-down  PM:320 
unmanaging  widget  PM:319 
what  if  requests  PM:322 
widget  for  vertical  tiles  RM:405-408 
width  PM:308 
get  values_hook  method  PM:  154, 265-266, 

"  502;  RM:  158, 275-278, 335 
(see  also  XtArgsProc) 
global  variables  PM:75, 77 
glyph  PM:502 

grabs  PM:351, 495, 502;  RM:431 
(see  also  XtAddGrab) 
(see  also  XtRemoveGrab) 
active  vs.  passive  PM:352 
adding  or  removing  explicitly  PM:372 
exclusive  vs.  nonexclusive  PM:352, 365 
grab  modes  PM:365 
in  dialog  boxes  PM:371 
keyboard  PM:351 
passive  PM:507 
pointer  PM:351 
reasons  for  in  menus  PM:353 
graphics  contexts  PM:119, 140, 157,502 
(see  also  XtDestroyGC) 
(see  also  XtGetGC) 
(see  also  XtReleaseGC) 
caching  PM:166, 168 
changing  PM:168, 176 
creating  PM:  166-170 
deallocating  RM:217 
destroying  RM:128 
exclusive  or  logical  function  PM:287 
freeing  PM:176, 183 
freeing  (R2)  RM:128 
hardcoding  values  in  PM:170 
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obtaining  RM:146-147 

read-only  PM:168 

reasons  for  PM:119 

setting  with  resources  PM:170 
graphics  (see  also  drawing) 

GraphicsExpose  events  PM:193,  220;  RM:51, 
468-469 

graphics  primitive  PM:503 
gravity  PM:503 
GravityNotify  events  RM:470 
Grayscale  PM:503 
Grip  widget  class  PM:19;  RM:368-369 

resources  RM:368 


H 


hardcoding,  resources  PM:38, 91,92 

translations  PM:48 
header  files,  not  included  twice  PM:139 

private  PM:508 

public  PM:508 
height  PM:308 

checking  in  initialize  method  PM:166 
hello  world  in  Xt  PM:31 
hexadecimal  color  specification  PM:434 
hints  PM:270-279,  503 

icon  position  PM:273 

position  PM:55 

size  PM:273 

size  increment  PM:273 
hook  RM:  158,  244 
host  access  list  PM:503 
hotspot,  in  cursor  PM:503 
Hyper  key  (see  modifiers) 


ICCCM  PM:1 1,269, 288, 29 1,298-302 
icon,  pop-ups  PM:272 

setting;  name  PM:278;  pixmap  PM:269, 
277-278 

starting  application  as  PM:273 
identifier  PM:503 
ifndef  statement,  to  prevent  include  files  from 

being  read  in  twice  PM:139 
implementation  file  (see  widget) 
include  files  PM:30,  50, 53, 136, 139 

in  widget  implementation  PM :  1 4 1 
inferiors  PM:503 
inheritance,  about  PM:18,  49, 54, 148-158 

adding  features  to  superclass  PM:157 


among  Athena  Widgets  PM:18 

among  Motif  widgets  PM:399 

among  Open  Look  widgets  PM:399 

in  widget  class  and  instance  record 
PM:137-138 

of  AT&T  PM:405 

of  chained  methods  PM:152 

of  conflicting  methods  PM:157 

of  Core  resources  PM:52,  54 

of  self-contained  methods  PM:151-152 

of  superclass  method  PM:  155 

resources  PM:  143 -145 

single  vs.  multiple  PM:503 

specifying  NULL  for  chained  methods 
PM:152-153 

styles  PM:151-152 

using  Xtlnherit  constants  PM :  1 5 1 

widget  not  using  resource  value  PM:56 
initial  size  PM:308 

initialize  method  PM:153, 165-170,  315, 503; 
RM:328-331 

(see  also  XtlnitProc) 

(see  also  XtProc) 

calling  XInterriAtom  from  PM:291 

in  constraint  widget  PM:330 
initialize_hook  method  PM:  153, 265,  503; 

RM:336 
input  queue,  determining  events  RM:83,  205 

(see  also  XtAppNextEvent) 

(see  also  XtAppPeekEvent) 

(see  also  XtAppPending) 

(see  also  XtPeekEvent) 

examining  head  RM:81-82,  204 
input,  from  file  PM:224-226 

from  pipe  PM:226-227 

input  events  method  RM:293-294 

input  focus  PM:504 

input  manager  PM:504 

input  source  masks  PM:224 

InputOnly  window  PM:504 

InputOutput  window  PM:504 
InputOurput  window  RM:460 
insert_child  method  PM:306,  323-324,  504; 

RM:339-340 

insert_position  method  RM:339,  342 
instance,  about  PM:18, 504 

instance  record  PM:136;  adding  variables  to 
PM:139;  allocating  storage  PM:140;  Bit- 
mapEdit  widget  PM:139;  contents 
PM:136 

instance  structure  PM:166 

part  structure;  constraints  in  PM:327 

structures  PM:135-162 
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Inter-Client  Communication  Conventions 

Manual  (see  ICCCM) 
Intrlnsics,  about  PM:8,  504;  RM:2 
functions  and  macros;  MenuPopdown 

PM:352;  MenuPopup  PM:352 
Intrinsic.h  PM:30, 141 
IntrinsicP.h  PM:141 
selection  timeout  RM:87 


JumpProc  RM:381 


key  events  (see  events  or  translations) 
key  translation,  registering  RM:238 

(see  also  XtKeyProc) 

(see  also  XtSetKeyTranslator) 
keyboard  focus,  about  PM:274, 389, 391, 504 

(see  also  XtAcceptFocusProc) 

(see  also  XtNinput  resource) 

(see  also  XtSetKeyboardFocus) 

accept/reject  method  RM:269 

redirecting  input  RM:236-237 

setting  PM:275 

styles  PM:275 

window  RM:462 
keyboard  grabbing  (see  grabs) 
keyboard,  mapping  RM:477 

shortcuts  (see  accelerators) 
keycodes,  about  PM:194,  391,  505 

translating;  keycode-to-keysym  RM:252-255; 
XtTranslateKey  RM:252-253;  XtTransla- 
teKeycode  RM:254-255 
KeymapNotify  events  RM:471 
KeyPress  events  PM:194, 196,391; 

RM:472-474 

Key  Release  events  PM:194, 196;  RM:472-474 
keysyms,  about  PM:194, 391,505 

(see  also  XtCaseProc) 

(see  also  XtConvertCase) 

converting  case  PM:200;  RM:28 1-282 

determining  case  RM:  114 

key  generated  PM:198 

keysymdef.h  PM:194,  197 

naming  conventions  PM:195 


Label  widget  class,  about  PM:177; 
RM:370-372 

creating  RM:372 

destroying  RM:372 

resources  RM:370-372 
laying  out  child  widgets,  example  PM:317, 

319 

layout  Form  method  PM:329 
LeaveNotify  events  PM:  195 -196, 234, 353; 

RM-.454-459 

LeaveWindow  events  PM:216 
lint  PM:42 
List  widget  class,  about  PM:19,  RM:373-377 

creating  RM:375 

destroying  RM:375 

UstWidgetClass  RM:373-377 

resources  RM:373-375 
loose  bindings  PM:244,  505 
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macros  PM:388-389 
mam  loop  PM:30, 34 

(see  also  XtAppMainLoop) 

(see  also  XtMainLoop) 

customizing;  example  PM:233 

internals  PM:233 
mapping,  about  PM:33, 53,  505 

(see  also  widget,  mapping) 

button  RM:477 

keyboard  RM:477 

MapNotify  events  RM:475-476 

MappingNotify  events  PM:193;  RM:477-478 

MapRequest  events  RM:479 

pop-up  shell;  XtPopup  RM:207-208 

unmapping  pop-up  shell;  XtPopdown 
RM:206 

widgets;  XtMapWidget  RM:185 
mechanism  without  policy  PM:10, 269 
memory  allocation  PM:392 

for  widget  instance  record  PM:  150 
MenuPopdown  PM:352;  RM:39 
MenuPopup  PM:352, 357;  RM:40-41 

argument  to  PM:358 
menus,  about  PM:345-38 1,408 

accelerators  in  PM:367,  371 

cascading  PM:347,  362 

drop-down  PM:347,  359 

grabbing  pointer  PM:353 

panes  in  PM:349 
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placing  pop-up  PM:357 

pointer  grabbing  PM:351 

popping  down  PM:35 1,359,  367;  MenuPop- 

down  RM:39 
popping  up  PM:352,  358;  MenuPopup 

RM:40-41 

popping  up  with  callbacks  PM:360 
puUdown  PM:347 

SimpleMenu  widget,  example  PM:368,  370 
spring-loaded  PM:347 
messages,  about  PM:29,  505 

OOP  vs.  Xt  PM:29 
Meta  key  (see  modifiers) 
methods,  about  PM:153-154, 505 
accept_focus  PM:154,  389,  391 
and  instance  structure  PM:136 
change_managed  PM:306-308,  319;  RM:340 
class_initialize  PM:153, 258, 381;  RM:331 
class_part_initialize  PM:153;  RM:331 
constraint  widgets;  destroying  PM:329; 

geometry_manager  PM:332;  initializing 

PM:329;  resizing  PM:336 
declarations  in  widget  implementation  file 

PM:147-148 

delete.child  PM:306, 323-324;  RM:340 
destroy  PM:154, 165, 183 
display_accelerators  PM:211 
drawing;  due  to  changes  in  set_values 

PM:175;  in  expose  PM:166 
expose  PM:29,  153,  165-166,  170-174,220; 

RM:296 

Form  layout  PM:329 
gadget;  expose  PM:378;  query_geometry 

PM:378;  set_values_almost  PM:378 
geometry_manager  PM:306,  311,  320-322; 

RM:340 
get_values_hook  PM:154, 265-266; 

RM:275-277;  example  PM:265;  example 

of  RM:275, 277 
in  OOP  PM:29 
inheritance;  adding  to  superclass  PM:157;  of 

superclass  PM:155 
initialize  PM:153, 165-170, 315 
initializejiook  PM:153,  265 
insert.child  PM:306,  323-324;  RM:339 
layout  Form  PM:329 
not  known  to  Xt  PM:329 
query_geometry  PM:154,  165,  180-182,306, 

321 

realize  PM:153,  274,  310,  315;  RM:331 
reconciliation  PM:157 
resize  PM:154,  165, 177-180,  306,  309 
resources,  and  set_values  PM:  174- 176 


set_values  PM:154,  165-166,  174-176, 
311-315 

set_values_almost  PM:154,  312,  322-323 

set_values_hook  PM:154, 265-266;  RM:275 
minimal  useful  size  PM:317 
mkfontdir  PM:444 
Mod  n  key  (see  modifiers) 
modal  cascade  (see  menus,  cascading) 
modal  pop  ups  (see  pop  ups) 
modifiers, !  PM:200 

adding  PM:198 

and  event  sequences  PM:202 

case-specifics  PM:200 

colon  PM:200-201 

displaying  list  PM:198 

for  button  events  PM:202 

keys,  about  PM:  196 -20 1,506;  Alt  key 
PM:197;  Ctrl  key  PM:197;  Hyper  key 
PM:197;  key  modifier  RM:500-506;  Meta 
key  PM:197;  Mod  n  key  PM:197;  Super 
key  PM:  197 

matching  exactly  PM:200 

negating  PM:199 

None  PM:200 

tilde  PM:199 
monochrome  PM:506 
Motif  PM:349, 399, 402 
motion  compression  PM:234 
MotionNotify  events  PM:196, 202, 216, 234, 

353;  RM:480-482 
multiple  toplevel  shells  PM:395 


N 


naming  conventions  (see  also  conventions) 

widgets  PM:449 
newlines,  in  translations  PM:190 
NoExpose  events  PM:193;RM:468-469 
nonfatal  error  (see  errors) 
nonmaskable  events  PM:191, 207, 218-220, 
506 

example  of  handlers  PM:219-220 
notify  modes  (see  translations) 


object,  about  PM:28, 506 
Object  class  PM:374 
object-oriented  programming  PM:28-29 
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object-oriented  programming,  about  PM:506 

obscure  PM:506 

occlude  PM:506 

OOP  (see  object-oriented  programming) 

optimization  PM:  124, 179,394 

options  -xrm  PM:86,  88 

options,  abbreviating  PM:87 

argument  styles  PM:90 

command  line  PM:86;  styles  PM:90 

custom  PM:246 

defining  your  own  PM:88 

handling  errors  in  PM:91 

options  table;  example  PM:88-89;  xbitmap 
PM:106 

standard  PM:86,  87;  RM:  13-14 
OR  operator  RM:50,  95,  221,  225 
overriding,  override  redirect  PM:272 

override_redirect  window  attribute  PM:157 

OverrideShell  widget  class  PM:272; 
RM:346-353 

standard  options  PM:91 

translations  PM:48-49 


padding  PM:506 
parent  PM:506 

parent  window  PM:507 
parsing,  command-line  arguments  PM:88-91 

translations  PM:48 
part  (vs.  record)  PM:137 
pipe  input  PM:226-227 
pixel  values  PM:120, 507 
pixmap,  about  PM:53, 171,  257,  507;  RM:295 

freeing  PM:183 

icon  PM:277 

updating  in  widget  PM:  116 
placing,  drop-down  menu;  example 
PM:360-361 

pop-up  menu;  example  PM:354,  357 
plane  PM:507 

(see  also  bit  plane) 

plane  mask  PM:507 
pointer  PM:507 

events  (see  events  or  translations) 

grabbing  (see  also  grabs),  PM:507 

pointing  device  PM:507 
pop  ups,  about  PM:17,  70,  507;  RM:8 

cascading  pop  ups;  about  PM:345 

creating  in  work  procedure  PM:232;  RM:323 

creating  just  before  popping  up  PM:76 

from  callback  function  PM:75 


linking  group  PM:272 

modal  PM:348,  505 

modeless  PM:348,  506 

moving  to  desired  position  PM:75 

OverrideSheU  PM:272 

sensitivity  PM:372 

spring-loaded  PM:348,  513;  RM:8 

using  PM:71-74 

when  application  is  iconified  PM:272 
pop-up  menus  PM:345 

(spring-loaded)  using  Box  widget  PM:354-358 
pop-up  shell,  (see  also  XtCreatePopupShell) 

creating  RM:  119-121 

mapping  RM:207-208 

unmapping  RM:206 
portability  PM:92,  224,  376,391-394 
position,  about  PM:55, 253 

hints  PM:273 

relative  to  root  window  PM:279 

setting  with  resources  PM:55 
PRIMARY  selection  PM:281 
printer  fonts  (see  fonts) 
private  header  file  (see  widget) 
private  instance  variables  PM:140 
process  input  RM:79 

(see  also  XtAppMainLoop) 
program  structure  PM:30 
properties,  about  PM:280,  508 

and  atoms  PM:288 
PropertyNotify  events  RM:483 
protocol,  about  PM:5 
PseudoColor  PM:508 

public,  functions,  about  PM:104,  158;  naming 
conventions  PM:114;  reasons  to  use 
PM:106 

header  file  (see  widget) 

instance  variables  (see  resources) 

routines  PM:340 
pull  down  menu  (see  menus) 


quarks  PM:262,508 

query_geometry  method,  about  PM:154, 165, 
180-182,  306, 321, 508;  RM:336-337 

in  composite  widget  PM:316-317 

in  constraint  widget  PM:339 

in  gadgets  PM:378 
querying  preferred  geometry  PM:320 
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R4  PM:96 

initialize_hook  and  set_values_hook  obsoles 
cence  RM:277 
raise  PM:509 

raw  event  handlers  PM:220;  RM:56-57 
real  estate  PM:509 

realization,  about  PM:33, 172, 176;  RM:296 
realize  method  PM:153, 274, 310,  315, 509; 

RM:33 1-332 
RealizeProc  RM:327 
rectangle  PM:509 
RectObj  class  PM:155,  374,  377 
redirect  PM:509 
redrawing  PM:23 
reference  pages,  list  RM:411,416 
regions  PM:172,379;  RM:51,  297 
registering/declaring  actions  (see  actions) 
registering,  callbacks  RM:44-45;  list 
RM:46-47 

converters  PM:257-260;  RM:48,  62-64,  216 

event  handlers  PM:21 8-220;  RM:49-50 

fatal  error  condition  procedure  PM:385-388; 
RM:85-86, 234 

file  RM:54-55,  65-66 

nonfatal  error  condition  procedure 

PM:385-388;  RM:88-89,  235,  246-247 

raw  event  handlers  RM:56-57 

work  procedures  PM:231-233;  RM:59,  68 
Release  4,  (R4)  PM:36, 345-346, 372 
removing,  callbacks  RM:218-220 

grabs  RM:223 

input  RM:224 

raw  event  handlers  RM:225-226 

timeouts  RM:227;  example  PM:229-230 

work  procedures  PM:232 
reparenting,  about  PM:279, 361,509 
ReparentNotify  events  RM:484 
reply  PM:509;  RM:341 
representation  type  PM:81-83, 239, 241, 509 
request  PM:510 
resize  method  PM:154, 165, 177-180, 306,  309, 

316, 336-337, 380, 510;  RM:333 
Resize  Request  events  RM:485 
resizing,  about  PM:65, 305, 311 

caching  old  size  PM:179 

parent  widget  RM:333 

reasons  PM:322 
resource  conversion  RM:131 
resource  list,  copying  (see  also  XtGetSub- 
values,  XtSetSubvalues) 

copying  from  ArgList  RM:242-243 


copying  to  argument  list  RM:  156-157 
resource  list,  retrieving  (see  also 

XtGetResourceList) 
(see  also  XtGetApplicationResources) 
resource  list,  updating  (see  also 

XtGetSubResources) 
default  values;  retrieving  RM:  148-149 
updating  RM:141-143;  by  name  or  class 

RM:154-155 
resources  RM:338-339 
resources  (see  also  resource  list) 
about  PM:22-23, 32, 36, 49, 52-54,  239-242, 

510;RM:6-8 

adv  antages  of  hardcoding  PM :  3  8 
and  set_values  method  PM:  174-176 
application  PM:80 
changing  value  PM:174 
checking  v  alidity  PM :  1 66 
class  PM:83 

classes  and  instances  PM:37 
comment  character  in  files  PM:244 
constraint  widget  PM:68;  RM:343-345 
copying;  from  ArgList  to  widget 

RM:244-245;  from  widget  to  argument  list 

RM:  158-159;  XtGetValues  RM:  158-159; 

XtSetValues  RM:244-245 
declaring  resource  list;  example  PM:240 
default  address;  interpreting  PM:242 
default  value;  converting  PM:254-255;  set 
ting  PM:83, 255 
defined  by  Core  PM:52 
defined  in  widget  implementation  file 

PM:  143-145 

defining  characteristics  PM:83-84 
defining  in  widget  PM:  143 -145 
Form  widget  PM:68,  326 
format;  of  definitions  PM:243-244 
getting  from  application  PM:50 
getting  resource  value;  example  PM:51 
in  instance  record  PM:140 
inheritance  of  PM:49, 143-145 
interactions  between  PM:54-57;  example 

PM:55 
loading;  from  .Xdefaults  PM:55;  withxrdb 

PM:55 

looking  up  values  PM:243-251 
loose  bindings  PM:244 
name  PM:83 

naming  conventions  PM:240 
precedence  rules  PM:249-251 
registering  resource  converter;  example 

PM:258 
representation  types  PM:81,  83,  241 
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resource  conversion  PM:83;  converters  in 
Xmu  PM:253;  method  RM:314-315;  (see 
also  XtConverter,  XtDirectConvert, 
XtResourceDefaultProc) 

resource  database  PM:510;  obtaining  for  dis 
play  RM:126 

resource  database  (see  also  XtDatabase) 

resource  database  sources  PM:245 

resource  file  format  RM:497 

resource  list;  example  PM:  82-83;  format 
PM:83-84 

Resource  Manager  PM:510  (see  also  actions) 

RESOURCE_MANAGER  property  PM:245 

resource  name  RM:  1 1 

resource  setting  PM:510 

resource  types  RM:11 

retrieving;  application  resources  PM:85-86; 
resource  default  at  run-time  PM:256 

setting;  for  multiple  widgets  PM:63-64;  for 
widget  hierarchy  PM:64;  for  widget  hierar 
chy  PM:64;  in  application  PM:50;  with 
XtSetValues  PM:50;  XtNinput  PM:276 

size  PM:242 

sources  priority  PM:246 

specifications  PM:249-251;  errors  in  PM:37; 
format  PM:37-38;  merging  of  duplicate 
PM:245-246;  wildcards  in  PM:243 

symbolic  constants  PM:38,  50 

tight  bindings  PM:244 

type  conversion  PM:38,  251-264 

type  converter,  XtConvert  RM:1 1 1-1 13 

types  table  PM:241 

use  of  classes  PM:241 

XtN  constants  PM:158 

XtNaccelerators  (Core)  PM:52 

XtNallowShellResize  (SheU)  PM:272 

XtNancestorSensitive  (Core)  PM:52 

XtNargc  (SheU)  PM:27 1-272 

XtNargv  (Shell)  PM:27 1-272 

XtNbackground  (Core)  PM:52 

XtNbackgroundPixmap  (Core)  PM:52 

XtNbaseHeight(SheU)  PM:272-273 

XtNbasewidth  (SheU)  PM:272 

XtNbaseWidth  (SheU)  PM:273 

XtNborderColor(Core)  PM:52 

XtNborderPixmap  (Core)  PM:52 

XtNborderWidth  (Core)  PM:52 

XtNcolormap  (Core)  PM:52 

XtNcreatePopupChUdProc  (SheU)  PM:271 

XtNdefaultDistance  (Form)  PM:325 

XtNdepth  (Core)  PM:52 

XtNdestroyCaUback  (Core)  PM:42,  52 

XtNgeometry  (SheU)  PM:27 1-274 


XtNheight  (Core)  PM:52 
XtNheightlnc  (SheU)  PM:272-273 
XtNhorizDistance  (constraint)  PM:325 
XtNiconic  (SheU)  PM:27 1-273 
XtNiconMask  (SheU)  PM:272 
XtNiconName  (Shell)  PM:272,  278 
XtNiconPixmap  (SheU)  PM:272,  278 
XtNiconWindow  (SheU)  PM:272 
XtNiconX  (SheU)  PM:27 1-273 
XtNiconY  (SheU)  PM:27 1-273 
XtNinitialState  (SheU)  PM:272 
XtNinput  (SheU)  PM:272, 275-276 
XtNinsertPosition  (composite)  PM:324 
XtNmappedWhenManaged  (Core)  PM:52, 
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XtNmaxAspectX  (SheU)  PM:272-273 
XtNmaxAspectY  (SheU)  PM:272-273 
XtNmaxHeight  (SheU)  PM:272-273 
XtNmaxWidth  (SheU)  PM:272-273 
XtNminAspectX  (SheU)  PM:272-273 
XtNminAspectY  (SheU)  PM:272-273 
XtNminHeight  (Shell)  PM:272-273 
XtNminWidth  (SheU)  PM:272-273 
XtNoverrideRedirect  (SheU)  PM:27 1-272 
XtNpixmap  (Core)  PM:116 
XtNpopdownCaUback  (Shell)  PM:360 
XtNpopupCaUback  (SheU)  PM:360-361 
XtNsaveUnder(SheU)  PM:272 
XtNscreen  (Core)  PM:52 
XtNsensitive  (Core)  PM:52 
XtNtide(SheU)  PM:27 1,278 
XtNtransient  (SheU)  PM:27 1-272 
XtNtranslations  (Core)  PM:47,  49,  52, 112 
XtNvertDistance  (constraint)  PM:325 
XtNwaitForWm  (SheU)  PM:272-272 
XtNwidth  (Core)  PM:52 
XtNwidthlnc  (SheU)  PM:272-273 
XtNwindowGroup  (SheU)  PM:27 1-272 
XtNwmTimeout  (SheU)  PM:27 1-272 
XtNx  (Core)  PM:52 
XtNy  (Core)  PM:52 

RGB,  color  model  PM:435-436 

root  PM:511 
root  window  PM:53, 511 

round  trip  request  PM:30, 260, 511 

rubber-band  outline  PM:177,287 
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save-set  PM:511 

save_under  window  attribute  PM:156 

saving  under  PM:156 

scan  line  PM:511 

order  PM:511 
screen,  screen  fonts  (see  fonts) 

about  PM:6,511 
scrollbars,  about  PM:15,  409,  422,  512 

adding  to  application  PM:109;  example 
PM:109 

adding  to  xbitmap  PM:108 

and  Expose  events  PM:114 

calculating  thumb  size  PM:113-116;  example 
PM:113-116 

controlling  scrolling  area  RM:378-382 

creating  PM:112 

Scroll  widget  PM:19 

ScroUbar  widget  PM:108-111;  RM:378-382; 
creating  RM:380;  destroying  RM:380; 
resources  RM:378-380 

scroUbarWidgetClass  RM:378-382 

setting  thumb  values  RM:381 
selections  PM:269,  280-302,  5 12 

SelectionClear  events  RM:486 

SelectionNotify  events  RM:487 

SelectionRequest  events  RM:488 

and  CurrenlTime  PM:289 

asserting  ownership  PM:288-289 

converting;  selection  PM:293-294;  standard 
selections  PM:299-301;  RM:284-285 

deleting  PM:301 

disowning  PM:302 

handling  large  selections  PM:301;  RM:285 

highlighting  selected  data  PM:284,  287-288 

highlighting  selection;  example  PM:284, 
287-288 

losing  selection  PM:289-297 

pasting  data  PM:292 

pasting  selection  PM:295-297;  example 
PM:295-296 

querying  for  desired  target  PM:298-302 

requesting  selection  PM:289-290 
selections,  selection  data  RM:132, 198-199 

method  RM:316-317;  obtaining  RM:151; 
obtaining  in  multiple  formats  RM:152-153 

(see  also  XtConvertSelectionProc) 

(see  also  XtDisownSelection,  XtSelection- 
CallbackProc) 

(see  also  XtGetSelection Value,  XtGetSelec- 
tionValues) 

(see  also  XtOwnSelection) 


selections,  selection  method 
(see  XtLoseSelectionProc,  XtSelection- 

DoneProc) 

selections,  selection  timeout  (see  timeouts) 
SelectionClear  events  PM:280,  289 
SelectionNotify  events  PM:280,  290,  295 
SelectionRequest  events  PM:193,  280,  282, 

290-291 

setting  timeout  PM:302 
target  types  PM:290-292 
XA_CLIPBOARD  PM:288,301-302 
XA_MULTIPLE  PM:301;RM:285 
XA_PRIMARY  PM:281,288 
XA_SECONDARY  PM:288 
XA_TARGETS  PM:29 1,298 
self-contained  methods  (see  inheritance) 
sensitivity  PM:54,75,92 
checking  state;  XtlsSensitive  RM:173 
in  pop-up  callbacks  PM:372 
setting  state;  XtSetSensitive  RM:241 
server,  about  PM:6,  512 
server  code;  guide  to  PM:491 
server  grabbing  PM:512 
server  resources;  freeing  PM:183 
set_values  method  PM:154, 165- 166, 174-176, 

311-312, 315, 512;  RM:319, 334-335, 343 
(see  also  XtSetArgsFunc,  XtSetValues,  XtSet- 

ValuesFunc) 
change  to  PM:456 
in  composite  widget  PM:316 
redrawing  due  to  changes  in  PM:175 
set_values_almost  method  PM:154, 312, 
~  322-323,  512;  RM:273-274,  335 
in  gadgets  PM:378 
set_values_hook  method  PM:154, 265-266, 

512;RM:275-276,335 
Shell  RM:346-353 

environment  variables  (see  environment  vari 
ables) 

Shell,  default  value  PM:458;  RM:351-352 
Shell  types;  ApplicationShell  RM:346;  Over- 
rideShell  RM:346;  Shell  RM:347; 
TopLevelShell  RM:346;  TransientShell 
RM:346;  VendorShell  RM:347;  WMShell 
RM-.347 

Shell  widget  class,  about  PM:17, 21,  32,  55, 
61,  66,  269;  RM:346-353;  reason  for  invisi 
bility  PM:63;  resources  PM: 271,  272-277, 
279;  types  RM:346-347;  XtlsShell 
RM:174;  XtNbasewidth  PM:272 
sibling  PM:512 
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single-line  Input  Held  PM:280 
sink,  in  Athena  Text  widget  PM:264 
size  PM:305 

hints  PM:273 

preferences  PM:320 

sizeof  PM:150 
Sme  gadgets  PM:367-378 
SmeBSB  gadgets  PM:367-378 
SmeLine  gadget  PM:367-378 
software  architecture,  about  PM:8 
source  code,  obtaining;  example  PM:34 
source  files  for  widget  PM:135 
source,  in  Athena  Text  widget  PM:264 
spring-loaded  pop  up  (see  pop  ups) 
stacking  order  PM:306, 341,513 
StaticColor  PM:513 
StaticGray  PM:513 
status  PM:513 
stdio.h  PM:141 
stipple  PM:513 
storage,  storage  block 

allocating  RM:181;  for  data  type  RM:189; 
XtNew  RM:189 

freeing  RM:140;  (see  also  XtFree) 

resizing  RM:215 

(see  also  XtMalloc) 

string,  copying;  XtNewString  RM:190 
StringDefs.h  PM:83 
StringDefs.h  header  file  PM:30, 50, 141; 

RM:507 
string,  error  message;  XtStringConversionWarn- 

ing  RM:248 

StrhigToWidget  resource  converter  PM:69 
structure  (see  also  XtOffset) 

determining  field's  byte  offset  RM:  193-194 

of  Xt  applications  PM:30 
subclass,  about  PM:19, 513 
submenus  (menus,  cascading) 
subparts  PM:150, 154,264-266 
subresources  PM:  150, 154,264-266 
Super  key  (see  modifiers) 
superclass,  about  PM:19,  149,  513 
syntax  functions  PM:91 


TCP/IP  PM:280 

templateWidgetClass  RM:383-390 
Text  widget,  about  PM:19,  414,  424; 
RM:39 1-402 

creating  RM:397 

default  bindings  RM:395-396 


edit  modes  RM:392 

resources  RM:392-394 
tight  bindings  PM:244, 513 
tiling,  about  PM:53,513 
time  PM:513 
timeouts,  about  PM:227 

adding  PM:227 

and  visibility  interest  PM:230 

callback  method  RM:321 

example  PM:228-229 

invoking  procedure  after  timeout  RM:67 

removing  PM:229-230 

selection  timeout;  setting  RM:240;  value 
RM:78,  87, 150 

(see  also  XtAddTimeout,  XtAppAddTimeOut) 

(see  also  XtAppSetSelectionTimeout,  XtGet- 
SelectionTimeout) 

(see  also  XtRemoveTimeOut,  XtSetSelection- 
Timeout) 

(see  also  XtTimerCallbackProc) 
toolkits,  initializing  internals  RM:250 

initializing  toolkit  and  display  RM:  1 6 1  - 1 65 

(see  also  Xtlnitialize,  XtToolkitlmtialize) 
top-level  widget  (see  Shell  widget) 

top-level  window  PM:514 

topLevelShell  widget  class  PM:270; 

RM:346-353 
training  in  Xlib  PM:489 
TransientShell  widget  class  PM:70, 74,  270; 

RM:346-353 

Translation  Manager  (see  actions) 
translations,  #  augment  directive  PM:48 

!  modifier  symbol  PM:200 

#  override  directive  PM:48 

#  replace  directive  PM:48 
(see  also  accelerators) 
(see  also  actions) 

(see  also  XtOverrideTranslations) 

about  PM:27,  39,  43, 47,  53,  514;  RM:7 

augmenting  PM:48 

colon  modifier  symbol  PM:200-201 

compiling;  table  RM:202-203;  when  widget 

class  initialized  PM:147;  XtParseTransla- 

tionTable  RM:202-203 
defining;  default  in  Core  class  part  PM:150; 

in  source  PM:49 
details  in  PM:  194-196 
differences  between  directives  PM:191 
directives  PM:191 
double-clicks  PM:201 
event  abbreviations  PM:192-193 
event  sequences  PM:201-203 
hardcoding  PM:48 
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in  widget  implementation  file  PM:  145 -147 

inheritance  PM:146 

interactions  between  PM:203-207 

keyboard  events  PM:194-195 

merging  PM:  112,  203 

merging  widget  translations  RM:93-94 

merging/overwriting  RM:197 

modifiers  PM:196-201, 198 

modifiers  and  event  sequences  PM:202 

Motion  events  PM:202 

new  lines  in  PM:190 

*Notify  details  PM:195 

order  PM:203-204 

overriding  PM:48-49 

parsing  PM:48 

removing  RM:256 

replacing  PM:48,  49 

resource  converters  PM:253 

syntax  PM:190 

tilde  modifier  symbol  PM:199 

translation  table  PM:514;  RM:499;  example 
PM:47;  syntax  PM:457 

(see  also  XtAugmentTranslations) 

(see  also  XtUninstallTranslations) 
traversal,  post-order  PM:508 

pre-order  PM:508 
TrueColor  PM:514 
type  converters  (see  also  resources) 

about  PM:93 

caching  PM:260 

explicitly  invoking  PM:261;  example 
PM:261 

format  PM:262-264 

passing  arguments  to  PM:259 

registering  PM:257-260 
type  property  PM:514 
typedefs  PM:140 

types  converters,  passing  arguments  to; 
example  PM:259 


L 


unman  aging  widget  PM:319 
UnmapNotify  events  RM:475-476 
upward  chaining  PM:152 
uunet  PM:34 
uwm  PM:346 


varargs  PM:95, 427 

variables,  resource  PM:446 

VcndorShcll  widget  class  PM:275 

viewable  PM:514 

Viewport  widget,  creating  RM:404 

Viewport,  Viewport  widget;  destroying 

RM:404;  inserting  child  RM:404;  remov 
ing  child  RM:404;  resources  RM:403-404 
ViewportWidgetClass  RM:403-404 

virtual  colormaps  PM:276 

virtual  crossing  RM:456 

visibility  interest  PM:  150, 230-231 

VisibilityNotify  events  PM:  150, 193; 
RM:489-490 

visible  PM:514 

visual  PM:514 
class  PM:514 

VPaned,  VPaned  widget;  about  RM:405-408; 
adding  pane  RM:406;  change  height  set 
tings  RM:407;  child  resources  RM:406; 
deleting  pane  RM:406;  destroying 
RM:408;  disabling  auto -reconfiguring 
RM:407;  disabling  pane  resizing  RM:407; 
disabling  resources  RM:405-406;  enabling 
auto-reconfiguring  RM:407;  enabling  pane 
resizing  RM:407 
VPanedWidgetClass  RM:405-408 


W 


warnings  (see  error  handling) 
calling  high-level  RM:9 1-92, 261-262 
handler,  (see  XtAppWarningMsg,  XtWarning, 

XtWamingMsg) 
listing  RM:491 
widget 

about  PM:8,15,514;RM:2 
actions;  example  PM:  184-1 85 
adding  to  parent  list  PM:17;  RM:182-184; 

XtManageChild  RM:182;  XtManageChil- 

dren  RM:  183-184 
application  context  PM:97-98;  getting 

RM:263;  XtWidgetToApplicationContext 

RM:263 

as  data  type  PM:33 

BitmapEdit  PM:66, 103-132, 177. 314, 461 
Box  widget  PM:21,351;RM:357-358; 

example  PM:61 

call  accept_focus  method  RM:97 
callback  list  (see  callbacks) 
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child  widget;  about  RM:15;  creating/manag 
ing  PM:61,307;RM:118;  layout  of 
PM:317 

class;  composite  widget  subclass  PM:16; 
determining  subclass  RM:175;  name 
defined  PM:150;  obtaining  RM:107;  veri 
fying  RM:106;  widgetClass  class  pointer 
PM:119;  XtCheckSubclass  RM:106; 
XtClass  RM:107;  XtlsComposite 
RM:169;  XtlsConstraint  RM:170;  Xtls- 
Shell  RM:174;  XtlsSubclass  RM:175 

Command  widget  PM:19, 38-39, 40-42, 75, 
104;  RM:359-362 

composite  widget,  about  PM:21,  305;  RM:14, 

169,  338-342;  management  PM:306;  rea 
sons  for  writing  PM:305;  writing  PM:312 

compound  PM:340-341 

constraint  widget,  about  PM:22,  305;  RM:16, 

170,  343-345;  management  PM:325;  writ 
ing  PM:325 

converting  (2  to  3)  PM:453 

Core  widget  PM:17, 116;  RM:383 

creating  PM:30,  80;  RM:  122-123;  additional 

top-level  widget  RM:69-70, 117;  child 

widget  RM:14;  custom  widget 

RM:383-390, 384;  working  window 

RM:124-125 
declaring  widget  class  record  pointer,  example 

PM:155 

default  size  PM:180 
defining  conventions  PM:  136, 244;  summary 

PM:162 
destroying  PM:26,  79, 183;  RM:129-130; 

XtDestroyWidget  RM:  129-130 
Dialog  widget  PM:20, 75, 340;  RM:363-364 
display  pointer  RM:134 
displaying  non-editable  string  RM:370-372 
dragging  PM:20;  attachment  point 

RM:368-369 

Exclusive  and  Nonexclusive  PM:407 
Form  widget  PM:20, 104, 326, 421; 

RM:365-367 

framework  of  code  PM:135-162 
geometry  (see  geometry  management) 
getting  data;  example  PM:105 
getting  widget  data  via  public  function 

PM:105 

Grip  widget  PM:19;  RM:368-369 
implementation  file  PM:135, 141-158;  actions 

table  PM:  145-147;  declaration  of  methods 

PM:147-148;  resources  PM:143-145; 

translation  table  PM:  145-147 
installing  accelerators  (see  accelerators) 


instance  structure  PM:166 

internals  PM:135-162 

Label  widget  PM:28, 116, 177,258; 

RM:370-372 
lifecycle  RM:4 

List  widget  PM:19;RM:373-377 
macros  for  getting  widget  information  PM:388 
management  (see  also  XtManageChild, 

XtManageChildren) 

PM:61, 180-182;  RM:171;  row-column 

geometry  RM:373-377;  XtlsManaged 

RM:171 
mapping  PM:53;  changing  map_when_man- 

aged  field  RM:239;  windows  PM:33; 

XtMapWidget  RM:185;  XtSetMap- 

pedWhenManaged  RM:29 
merging  translations  RM:93-94 
methods  (see  XtCreate Widget) 
modal  widget;  redirecting  input  RM:52-53, 

223;  XtAddGrab  RM:52-53;  XtRemo- 

veGrab  RM:223 
moving/resizing  PM:53;  RM:  109-1 10; 

XtConfigureWidget  RM:  109-1 10;  XtMo- 

veWidget  RM:187 
naming  conventions  PM:449 
necessary  include  files  PM:136 
parent  widget  PM:111;  returning  RM:200; 

XtParent  RM:200 

popping  down;  Menupopdown  RM:39 
popping  up  PM:75-76;  Menupopup 

RM:40-41 

private  header  file  PM:  135, 136-140 
procedure  RM:322 
public  header  file  PM:135,  158-160 
realizing  PM:176;  RM:172,  213-214;  method 

RM:312-313;  XtlsRealized  RM:172; 

XtRealizeProc  RM:312-313;  XtReal- 

izeWidget  RM:213-214 
record  size  PM:150 
removing  PM:17;  XtUnmanageChildren 

RM:258;  XtUnmanageChild  RM:257 
resizing  PM:65, 177-180,  306-314;  RM:333; 

by  application  PM:312;  by  parent 

PM:311;  per  core  dimensions  RM:230; 

reasons  for  PM:322;  resize  method 

PM:336;  XtMakeResizeRequest  RM:180; 

XtResizeWidget  RM:229;  XtResizeWin- 

dow  RM:230 
retrieving  event  mask  RM:95-96;  XtBuild- 

EventMask  RM:95-96 
returning  screen  pointer,  XtScreen  RM:231 
Scroll  widget  PM:257 
Scrollbar  widget  PM:19,  66, 108;  RM:378-382 
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ScrollBox  widget  PM:314 

scrolling  viewing  area  in  another  widget 

RM:378-382 
sensitivity  PM:54, 235 

sets;  about  PM:8, 17, 18;  Motif  PM:18;  spe 
cial  defaults  PM:275 
Shell  widget,  about  PM:17, 21,  61, 104, 269; 

RM:174 

source  file  PM:135;  RM:387 
subclass;  XtlsSubclass  RM:175 
superclass;  inheritance  PM:54;  obtaining 

RM:249;  XtlsSuperclass  RM:249;  XtSu- 

perclass  RM:249 
techniques  for  writing  PM:160 
Text  widget  PM:19,  75,  264,  414,  424; 

RM:39 1-402 

text-editing  widget  RM:39 1-402 
translating;  coordinates  RM:251;  name  to 

instance  RM:188;  window  and  display 

pointer  RM:265;  XtNameTo Widget 

RM:188;  XtTranslateCoords  RM:251; 

XtWindowToWidget  RM:265 
unmapping;  XtUnmapWidget  RM:259 
Viewport  PM:21, 108;  RM:403-404 
VPaned  widget  PM:20,  66;  RM:405-408 
WidgetProc  RM:327 

WidgetToApplicationContext  macro  PM:394 
WidgetWrap  PM:96 
Window  widget  RM:385 
window;  destroying  RM:260;  returning 

RM:264;  XtUnrealizeWidget  RM:260; 

XtWindow  RM:264 
windowless  (see  gadgets) 
widget  classes,  about  PM:17 
applicationShell  (Intrinsics)  PM:270 
Box  (Athena)  PM:66 
Command  (Athena)  PM:19,  40-43,  47,  65 
composite  (Intrinsics)  PM:16,  61, 137 
constraint  (Intrinsics)  PM:137 
Core  (Intrinsics)  PM:17, 52, 137;  RM:327-337 
Dialog  (Athena)  PM:71,75 
Form  (Athena)  PM:68-69 
Grip  (Athena)  PM:66 
inheritance  among  (Athena)  PM:18 
initialize  method;  XtlnitProc  RM:302-303; 

XtProc  RM:311 
Label  (Athena)  PM:19,36,240 
OverrideShell  (Intrinsics)  PM:270, 272 
ScroU  (Athena)  PM:15,  39, 42,  66 
Shell  (Intrinsics)  PM:17,  32,  55,  61,  66,  269 
Simple  (Athena)  PM:19 
Text  (Athena)  PM:75,  264 
topLevelShell  (Intrinsics)  PM:270 


TransientSheU  (Intrinsics)  PM:70,  74,  270 

VendorShell  (Intrinsics)  PM:275 

VPaned  (Athena)  PM:66 
WidgetWrap  PM:429 
width  PM:308 

checking  in  initialize  method  PM:166 
wildcards,  in  font  names  PM:441 

in  resource  specifications  PM:37,  243 
window  (see  also  XtCreate Window) 

creating  widget's  working  window 
RM:  124-125 

geometry  PM:445 

InputOutput  RM:460 

keyboard  focus  RM:462 

background  PM:156 

backing_store  PM:156 

bit_gravity  PM:156 

border  PM:156 

colormap  PM:156 

cursor  PM:157 

event_mask  PM:157 

override_redirect  PM:157 

save_under  PM:156 

setting  in  realize  method  PM:157 
window  gravity  PM:515 
window  manager,  about  PM:11, 31,  65-66, 
269-279, 305, 5 15;  RM:352 

and  decoration  PM:279 

and  icons  PM:277-279 

click-to-type  PM:274 

colormaps  PM:276,  277 

focusing  styles  PM:196 

hints  PM:1 1,270-279 

input  models  PM:274 

interacting  with  PM:270-279 

keyboard  focus  PM:274-276 

listener  PM:505 

pointer-focus  PM:274 

real-estate-driven  PM:274 

reparenting  PM:279,  361 

screen  layout  PM:273-274 
WindowObj  class  PM:155,375 
work  procedures,  about  PM:23 1-233,  RM:59 

(see  also  XtAddWorkProc,  XtAppAddWork- 
Proc) 

(see  also  XtAppRemoveWorkProc, 
XtWorkProc) 

creating  pop  up  in,  example  RM:323 

registering  RM:68 

removing  PM:232;  RM:228 
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X  Consortium  address  PM:490 

X  protocol  PM:5, 280 

X  source  software  PM:485 

X  Toolkit  (see  toolkits) 

X,  about  PM:3 

XA_CLIPBOARD  (see  selections) 

XA_MULTIPLE  property  (see  selections) 

XA_MULTIPLE  property  (see  selections) 

XAPPLRESDIR  environment  variable 

PM:245 

XA_PRIMARY  property  (see  selections) 
XA_PRIMARY  (see  selections) 
XA_SECONDARY  (see  selections) 
XA_TARGETS  atom  (see  selections) 
Xatom.h  PM:288,290 
Xaw;  PM:36 
x bitmap  application;  PM:461 

xbitmapl;  example  PM:104-107 

xbitmap2;  example  PM:107-116 

xbitmapS;  example  PM:1 16-122 

xbitmap4;  example  PM:  123-132 
XChangeGC  Xlib  function  PM:168 
XChangeKeyboardMapping  RM:477 
XClearArea  Xlib  function  PM:175 
xclipboard  PM:300-302 
XConfigureWindow  PM:341,RM:449-450, 
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XConvertSelection  RM:487 
XCopyArea  Xlib  function  PM:122, 174, 193; 

RM:297 
XCopv  Colormap AndFree  Xlib  function 

PM:277 
XCopyPlane  Xlib  function  PM:122, 174, 193; 

RM:297 

XCreateGC  Xlib  function  PM:  120, 166 
XCreate Window  Xlib  function  PM:158 
Xdefaults  Hie  PM:55,245 
xedit  PM:280 
XENVIRONMENT  environment  variable 

PM:245 
xev  PM:198 
XEvent  union  RM:437 
xfarewelLc,  example  PM:43-45 
xfd  (font  displayer)  PM:441 
XFlush  Xlib  function  PM:394 
XGCValues  structure  PM:168 
XGetlconSizes  Xlib  function  PM:279 
XGetModifierMapping  RM:478 
XGetMotionEvents  RM:481 


XGetPointerMapping  RM:478 
XGetStandardCoIormap  Xlib  function 

PM:277 

xgoodbye.c,  example  PM:40 
XGrabButton  Xlib  function  PM:353 
XGrabKey  Xlib  function  PM:353 
XGrabPointer  Xlib  function  PM:352 
xhello.c,  example  PM:31-32 
XInternAtom  Xlib  function  PM:290-291 
Xlib  PM:36, 170, 172, 176 

Xlib  Interface  RM:17 
xload  PM:275 

XLookupString  Xlib  function  PM:391 
XLowerWindow  Xlib  function  PM:341 
XMapRaised  RM:479 
XMapWindow  RM:479 
xmh  PM:68,280 
xmodmap  PM:198 
XMoveResizeWindow  RM:485 
Xmu  PM:36, 259, 299 
XmuConvertStandardSelection  PM:300-301 ; 

RM:285 
XmuConvertStandardSelection  Xmu  function 

PM:299 

XmuInternAtom  PM:299 
Xmu  Intern  Atom  Xmu  function  PM:299 
Xmu,  resource  converters  in  PM:253 
XNextEvent  Xlib  function  PM:31 1 
XParseGeometry  Xlib  function  PM:274 
XQueryPointer  RM:481 
XRaiseWindow  Xlib  function  PM:341 
xrdb  PM:55, 243, 245 
XRecflnRegion  Xlib  function  PM:172; 

RM:297 

XRefreshKeyboardMapping  RM:478 
XResizeWindow  RM:485 
XRestackWindows  Xlib  function  PM:341 
XrmOptionDescRec  RM:163 

example  PM:88-89 

format  PM:89 

structure  PM:88 

XrmoptionlsArg  argument  style  PM:90 
XrmOptionKind  enum  values  PM:90 
XrmoptionNoArg  argument  style  PM:90; 

RM:165 

XrmoptionResArg  argument  style  PM:90 
XrmoptionSepArg  argument  style  PM:90 
XrmoptionSkipArg  argument  style  PM:90 
XrmoptionSkipLine  argument  style  PM :90 
XrmoptionStickyArg  argument  style  PM:90 
XrmStringToQuark  Xlib  function  PM:262 
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XSelectlnput  Xlib  function  PM:207, 216 
XSendEvent  RM:444, 487-488 
XSetErrorHandler  Xlib  function  PM:385 
XSetlnputFocus  RM:463 
XSetlnputFocus  Xlib  function  PM:390; 

RM:463 

XSettOErrorHandler  Xlib  function  PM:385 
XSetPointerMapping  RM:477 
XSync  Xlib  function  PM:394 
Xt  Intrinsics  (see  Intrinsics) 
XtAcceptFocusProc  RM:269 
XtActionProc  PM:46;  RM:270-272 
XtAddActions  PM:45, 47, 145, 381,  393; 

RM:42-43 
XtAddCallback  PM:42,  253;  RM:44-45 

arguments  PM:42 

XtAddCallbacks  PM:80;  RM:46-47 
XtAddConverter  PM:259,393;  RM:48 

arguments  PM:258 
XtAddEventHandler  PM:215-216;  RM:49-50 

arguments  PM:218 

whentocaU  PM:218 
XtAddExposureToRegion  RM:51 
XtAddGrab  PM:372;  RM:52-53 
XtAddlnput  PM:224, 226, 393;  RM:54-55 
XtAddRawEventHandler  PM:220;  RM:56-57 
XtAddress  address  mode  constant  PM:260 
XtAddressMode  enum  PM:260 
XtAddTimeOut  PM:227;  RM:58 
XtAddWorkProc  PM:231;RM:59 
XtAlmostProc  RM:273-274, 335 
XtAppAddActions  PM:98,  393;  RM:60-61 
XtAppAddConverter  PM:393;  RM:62-64 
XtAppAddlnput  PM:393;  RM:65-66 
XtAppAddTimeOut  RM:67 
XtAppAddWorkProc  RM:68 
XtAppContext  PM:97 
XtAppCreateShell  PM:30, 98, 270, 393, 395; 

RM:69-70 

XtAppError  PM:386,393;  RM:71 
XtAppErrorMsg  PM:393;  RM:72-73 
XtAppGetErrorDatabase  PM:393;  RM:74 
XtAppGetErrorDatabaseText  PM:393; 

RM:75-77 

XtAppGetSelectionTimeout  PM:393 
XtAppInitiallze  PM:97, 243 
XtAppMainLoop  PM:98,  393;  RM:79 
XtAppNextEvent  PM:393-394;  RM:80 
XtAppPeekEvent  PM:393-394;  RM:81-82 
XtAppPending  PM:393-394;  RM:83 
XtAppProcessEvent  PM:393-394;  RM:84 


XtAppSelectionTimeout  RM:78 
XtAppSetErrorHandler  PM:393;  RM:85 
XtAppSetErrorMsgHandler  PM:393;  RM:86 
XtAppSetSelectionTimeout  PM:393;  RM:87 
XtAppSetWarningHandler  PM:393;  RM:88 
XtAppSetWarningMsgHandler  PM:393; 

RM:89 

XtAppTimeOut  PM:393 
XtAppWarning  PM:386, 393;  RM:90 
XtAppWarningMsg  PM:393;  RM:91-92 
XtAppWorkProc  PM:393 
XtArgsFunc  RM:275-276, 335 
XtArgsProc  RM:277-278,  335-336, 339 
XtArgVal  PM:92 
XtAsciiSinkCreate  RM:401 
XtAsciiSinkDestroy  RM:401 
XtAugmenfTranslations  PM:48, 113; 

RM:93-94 

reasons  to  use  PM:112 

XtBaseOffset  address  mode  constant  PM:260 
XtBuildEventMask  RM:95-96 
XtCallAcceptFocus  PM:154, 390-391;  RM:97 
XtCallbackExclusive  PM:79,  352;  RM:98-99 
XtCallbackList  RM:279 
XtCallbackNone  PM:79,352;  RM:100 
XtCallbackNonexclusive  PM:79, 352;  RM:101 
XtCalibackPopdown  PM:352;  RM:  102-103 
XtCallbackProc  RM:279-280 
XtCallbackRec  RM:279 

format  PM:80 

XtCallCallbacks  PM:39;  RM:104 
XtCalloc  PM:183,392;RM:105 
XtCaseProc  RM:28 1-282 
XtCaseProc  function  prototype  PM:392 
XtCheckSubclass  RM:106 
XtClass  RM:107 
XtCIoseDisplay  RM:108 
XtConfigureWidget  PM:52;  RM:  109-1 10, 334, 

341 

XtConvert  PM:93,261;RM:111-113 
XtConvertArgRec  PM:259 
XtConvertCase  PM:392;RM:114 
XtConverter  RM:286-289 
XtConvertSelectionProc  PM:282, 289; 

RM:283-285 
XtCreateApplicationContext  PM:30, 97-99; 

RM:115-116 
XtCreateApplicationSheU  PM:393, 395; 

RM:117 
XtCreateManagedWidget  PM:30, 33,  64, 94, 

140,  243;  RM:14, 118,340 
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XtCreatePopupShell  PM:74,  270,  348; 

RM:119-121 
XtCreateWidget  PM:30,  63, 140, 165, 243; 

RM:122-123,339,344 
hardcoding  resources  with  PM:92 
XtCreateWindow  PM:158;RM:124-125 
XtCWQueryOnly  mask  PM:322;  RM:340-341 
XtDatabase  RM:126 
XtDefaultBackground  PM:277 
XtDefaultBackground  constant  PM:253, 264 
XtDefaultFont  constant  PM:253 
XtDefaultForeground  constant  PM:253, 264, 

277 

XtDestroyAppIicationContext  RM:127 
XtDestroyGC  PM:176;RM:128 
XtDestroy Widget  PM:165, 324;  RM:  129-130, 

339, 345 

XtDirectConvert  PM:261;RM:131 
XtDiskSourceCreate  RM:401 
XtDiskSourceDestroy  RM:401 
XtDisownSelection  PM:302;  RM:132 
XtDispatchEvent  PM:233;RM:133 
XtDisplay  RM:134 
XtDisplay  macro  PM:261 
XtDisplaylnitialize  PM:30;RM:135-136 
xterm  PM:274,346 
XtError  PM:386,  387,393;  RM:137 
XtErrorHandler  RM:290 
XtErrorMsg  PM:386, 387, 393;  RM:  138-139 
XtErrorMsgHandler  RM:29 1-292 
xtetris  PM:227, 228-229 
XtEventHandler  RM:293-294 
XtExposeProc  PM:147;  RM:295-298,  332 
XtFree  PM:  183, 297, 392;  RM:  140 
XtGeometryAlmost  PM:321;  RM:335,341 
XtGeometry Almost  return  value  PM:182 
XtGeometryDone  RM:340 
XtGeometryDone  return  value  PM:321 
XtGeometryHandler  RM:299-301, 336 
XtGeometryMask  RM:  178,  211,273,300 
XtGeometryNo  PM:182;RM:341 
XtGeometryNo  return  value  PM:321 
XtGeometryResult  PM:320-321;  RM:178,  180, 

211,300 

XtGeometryResult  enum  PM:182 
XtGeometryYes  PM:182;RM:340 
XtGeometryYes  return  value  PM:321 
XtGctApplicationRcsourccs  PM:80,  243,  260; 

RM:141-143 

XtGetErrorDatabase  PM:387, 393;  RM:144 
XtGetErrorDatabaseText  PM:387, 393; 


RM:145 
XtGetGC  PM:120, 166, 168, 176;  RM:146-147 

when  not  to  use  PM:169 
XtGetResourceList  PM:145;  RM:148-149 
XtGetSelectionTimeout  PM:302,  393;  RM:150 
XtGetSelectionValue  PM:282, 289-291, 299; 

RM:151 

XtGetSelection Values  PM:302;  RM:  152-153 
XtGetSubresources  PM:260,  266; 

RM:154-155, 156-157 
XtGetSubvalues  PM:266;RM:  156-157 
XtGetValues  PM:23, 50-51, 75, 136, 361; 

RM:  158-159, 345 
bugfix  PM:458 

XtGrabNone  grab  mode  PM:371 
XtHasCallbacks  PM:388;  RM:160 
X tlMAIternatelnput  constant  PM:234 
Xtlmmcdiate  address  mode  constant  PM:260 
XtlMTimer  constant  PM:234 
XtfMXEvent  constant  PM:234 
Xttnherit  constants  PM:151 
XtlnheritDeleteChild  constant  PM:324 
XtlnheritGeometryManager  constant 

PM:321 

XflnheritlnsertChild  RM:339 
XtlnheritlnscrtChild  constant  PM:324 
XtlnheritRealize  constant  PM:155 
XttnheritSetValuesAlmost  RM:335 
XtlnherltSetValuesAlmost  constant  PM:323 
Xttnitialize  PM:30, 32, 74,  87, 170,  243, 246; 

RM:161-165 
arguments  PM:32,  33 
passing  options  table  to  PM:90 
XtlnitProc  RM:302-303, 330,  345 
XtlnputCallbackProc  RM:304-305 
XflnstallAccelerators  PM:205;  RM:  166- 167 
XtlnstallAllAccelerators  PM:205,  209; 

RM:168 

XtlnternAtom  Xlib  function  PM:288 
XtlsComposite  PM:388;  RM:169 
XtlsConstraint  RM:170 
XtlsManaged  PM:388;RM:171 
XtlsRcalizcd  PM:  172,  388;  RM:  172,  296 
XtlsSensitive  PM:388;  RM:173 
XflsShell  RM:174 
XtlsSubclass  PM:388;RM:175 
XtKeyProc  RM:306-308 
XtKeyProc  function  prototype  PM:392 
XtLoseSelectionProc  PM:289;  RM:309 
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XtMainLoop  PM:30,  34,  141,  230,  311,  393; 

RM:176 

and  multiple  application  contexts  PM:394 
XtMake  Geometry  Request  PM:311-312,  320; 

RM:  177-179,  340 

XtMakeReslzeRequest  PM:322;  RM:180 
XtMalloc  PM:  1 83, 392;  RM:  1 8 1 
XtManageChild  PM:33;  RM:182 
XtManageChildren  PM:30,  33;  RM:183-184 
XtMapWidget  PM:319;  RM:185 
XtMergeArgLists  PM:95;RM:186 
XtMoveWidget  PM:52, 308,  319;  RM:187, 341 
XtNameToWidget  PM:388 
XtNbasewidth  (SheU)  PM:272 
XtNew  PM:266,392;RM:189,275 
XtNewString  PM:392;  RM:190 
XtNextEvent  PM:233,393;  RM:191 
XtNsensitive  resource  PM:75 
XtNumber  RM:192 
XtOffset  RM:  193-194 
XtOffset  macro  PM:83,242 
XtOpenDisplay  PM:98, 396;  RM:  195-196 
XtOrderProc  RM:310,  342 
XtOverrideTransIations  PM:49,  112-113; 

RM:197 

reasons  to  use  PM:112 
XtOwnSelection  PM:281,  288-289; 

RM:198-199 

XtPanedAllowResIze  RM:407 
XtPanedSetMinMax  RM:407 
XtPanedSetReflgureMode  RM:407 
XtParent  RM:200 

XtParseAcceleratorTable  PM:210;  RM:201 
XtParseTranslationTable  PM:48, 113, 147, 

210;  RM:202-203 

XtPeekEvent  PM:234,  393;  RM:204 
XtPending  PM:234,  393;  RM:205 
XtPointer  PM:376 
XtPointer  data  type  PM:256 
XtPopdown  PM:7 1,352, 357;  RM:206, 352 
XtPopup  PM:71,  352,  365;  RM:207-208,  347, 

352 

XtPopupSpringLoaded  (R4)  PM:353 
XtProc  RM:31 1,327 
XtProcessEvent  PM:234, 393;  RM:209 
XtQueryGeometry  PM:308,310,  312; 

RM:210-212 
XtR  Accelerator  Table  representation  type 

PM:253 

XTransIateCoordinates  Xlib  function  PM:361 
XtRBackingStore  representation  type 


PM:257 

XtRBool  representation  type  PM:253 
XtRBoolean  representation  type  PM:253 
XtRCallhack  representation  type  PM:258 
XtRCallProc  representation  type  PM:242, 

255 

XtRCursor  representation  type  PM:253, 257 
XtRDimension  representation  type  PM:253 
XtRDisplay  representation  type  PM:253 
XtRealizeProc  RM:312-313,331 
XtRealizeWidget  PM:30, 33, 153, 308, 

310-311, 319;  RM:213-214 
XtRealloc  PM:392;  RM:215 
XtRegisterCaseCon verier  PM:392;  RM:216 
XtReleaseGC  PM:176;  RM:217 
XtRemoveAccelerators  PM:206 
Xt  Remove  Actions  PM:145 
XtRemoveAUActions  PM:145 
XtRemoveAllCalibacks  RM:218 
XtRemoveCallback  PM:80, 360;  RM:219 
XtRemoveCallbacks  PM:80;  RM:220 
XtRemoveEventHandler  PM:183,220; 

RM:221-222 

XtRemoveGrab  PM:372;  RM:223 
XtRemovelnput  PM:226;  RM:224 
XtRemoveRawEventHandler  PM:220; 

RM:225-226 

XtRemoveTimeOut  PM:183,  229;  RM:227 
XtRemoveWorkProc  PM:231, 232;  RM:228, 

323 

XtResizeWidget  PM:308, 319;  RM:229,  341 
XtResizeWindow  RM:230 
XtResource  PM:239 
XtResourceDefaultProc  RM:314-315 

example  PM:256 
XtResourceQuark  address  mode  constant 

PM:260 
XtResourceString  address  mode  constant 

PM:260 

XtRFile  representation  type  PM:253 
XtRFIoat  representation  type  PM:253 
XtR  Font  representation  type  PM:253 
XtRFontStruct  representation  type  PM:253 
XtRFunction  representation  type  PM:258 
XtRImmediate  representation  type  PM:242, 

255 

XtRInt  representation  type  PM:253 
XtRJustify  representation  type  PM:257 
XtROrientation  representation  type  PM:257 
XtRPixel  representation  type  PM:253 
XtRPixmap  representation  type  PM:257 
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XtRPosition  representation  type  PM:253 
XtRShort  representation  type  PM:253 
XtRTranslation Table  representation  type 

PM:253 
XtRUnsignedChar  representation  type 

PM:253 

XtRWidget  representation  type  PM:257 
XtScreen  RM:231 
XtScroUbarSetThumb  RM:381 
XtSelectionCallbackProc  PM:282; 

RM:316-317 

XtSeiectionDoneProc  PM;282;  RM:318 
XtSetArg  PM:50,  51, 93, 119;  RM:232-233 
XtSetErrorHandler  PM:387, 393;  RM:234 
XtSetErrorMsgHandler  PM:387, 393; 

RM:235 

XtSetKeyboardFocus  PM:391;  RM:236-237 
XtSetKeyTranslator  RM:238 
XtSetMappedWhenManaged  RM:239 
XtSetSelectionTimeout  PM:302, 393;  RM:240 
XtSetSensitive  PM:75,371;RM:241 
XtSetSubvalues  PM:266;  RM:242-243, 275 
XtSetValues  PM:23, 49-51, 136, 140, 154, 157, 

165-166, 174-176,  319, 338;  RM:244-245, 

334-335, 345 

XtSetValuesFunc  RM:319,334 
XtSetValuesFunc  function  prototype  PM:175 
XtSetWarningHandler  PM:387, 393;  RM:246 
XtSetWarningMsgHandler  PM:387, 393; 

RM:247 
XtStringConversionWarning  PM:263, 387; 

RM:248 

XtStringProc  RM:320,336 
XtStringSourceCreate  RM:401 
XtStringSourceDestroy  RM:402 
XtSupcrclass  RM:249 
XtTextBlock  RM:399 
XtTextChangeOptions  RM:400 
XtTextDisableRedisplay  RM:399 
XtTextDisplay  RM:400 
XtTextEnableRedisplay  RM:399 
XtTextGettnsertionPoint  RM:400 
XtTextGetOptions  RM:400 
XtTextGetSelectionPos  RM:398 
XtTextGetSource  RM:401 
XtTexflnvalidate  RM:399 
XtTextReplace  RM:398 
XtTextSetlnsertionPoint  RM:400 
XtTextSetLastPos  RM:400 
XtTextSetSelection  RM:397 
XtTextSetSource  RM:401 


XtTextTopPosition  RM:400 
XtTextUnsetSelection  RM:398 
XtTimeOut  PM:393 
XtTimerCallbackProc  RM:321 
XtToolkitlnitialize  PM:30, 98, 243;  RM:250 
XtTranslateCoords  PM:75, 360-361;  RM:251 
XtTranslateKey  PM:392;  RM:252-253 
XtTranslateKeycode  PM:392;  RM:254-255 
XtUninstallTranslations  RM:256 
XtUnmanageChild  PM:319;RM:257 
XtUnmanageChildren  PM:319;  RM:258 
XtUnmapWidget  PM:319;RM:259 
XtUnrealizeWidget  RM:260 
XtVaCreateArgsList  PM:428 
XtVaGetApplicationResources  PM:260 
XtVaGetSubresources  PM:260 
XtVersion  constant  PM:151 
XtVersionDontCheck  constant  PM:151 
XtWarning  PM:386-387, 393;  RM:261 
XtWarningMsg  PM:386-387, 393;  RM:262 
XtWidgetGeometry  PM:320-323 
XtWidgetGeometry  structure  PM:  180- 182 
XtWidgetProc  PM:  148;  RM:322, 332-345 
XtWidgetToApplicationContext  RM:263 
XtWindow  PM:176,378;RM:264 
XtWindowToWidget  PM:389;  RM:265 
XtWorkProc  PM:393;  RM:323-324 
XUnGrabPointer  Xlib  function  PM:352 
XView  PM:10 
XYPixmap  PM:515 


zoomed  window  PM:515 
ZPixmap  PM:515 
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overseas  locations  offer  international  customers  faster  order  processing,  more  local  bookstores 
and  local  distributors,  an  increased  representation  at  trade  shows  worldwide,  as  well  as  the  high 
level,  quality  service  our  customers  have  always  received. 
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Volume  Four,  X  Toolkit  Intrinsics  Programming  Manual,  is  a  complete  pro 
grammer's  guide  to  the  X  Toolkit  (Xt).  Xt  is  a  library  of  C  language  routines 
designed  to  facilitate  the  design  of  user  interfaces,  with  reusable  components 
called  widgets.  This  book  uses  the  Athena  widgets  to  demonstrate  how  to  use 
existing  widgets,  but  it  is  equally  applicable  to  and  provides  a  good  introduction 
to  programming  with  any  other  widget  set  based  on  Xt,  such  as  OSF/Motif  or 
AT&T's  OPEN  LOOK  widget  set.  It  includes  chapters  on: 

•  Introduction  to  the  X  Window  System 

•  Building  applications  with  widgets 

•  A  bitmap  editor  constructed  with  widgets 

•  Inside  a  widget 

•  Basic  widget  methods 

•  Events,  translations  and  accelerators 

•  Event  handlers,  timeouts  and  work  procedures 

•  Resource  management  and  type  conversion 

•  Interclient  communication 

•  Geometry  management 

•  Menus,  gadgets  and  cascaded  pop  ups 

•  Miscellaneous  Toolkit  programming  techniques 

•  Comparison  of  Athena,  OSF/Motif  and  AT&T's  OPEN  LOOK 
widgets 

as  well  as  a  glossary,  a  master  index  and  many  useful  appendices. 

This  book  is  designed  to  be  used  with  Volume  Five,  X  Toolkit  Intrinsics 
Reference  Manual,  which  provides  reference  pages  for  each  of  the  Xt  functions 
and  the  widget  classes  defined  by  Xt. 
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